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Foreword 



rd , 



This Technical Specification has been produced by the 3 Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



£75/ 



3GPP TS 31.131 version 7.0.0 Release 7 7 ETSI TS 131 131 V7.0.0 (2007-06) 



Scope 



A Subscriber Identity Module Application Programming Interface (SIM API) has been defined in TS 42.019 [4] as a 
technology-independent API by which toolkit applications and (U)SIMs co-operate. That specification is independent 
of the programming language technology used to create the application, the platform used to host the application and 
the runtime environment used to execute the application. 

The present document includes information applicable to (U)SIM toolkit application developers creating applications 
using the C programming language ISO/IEC 9899 [7]. The present document describes an interface between toolkit 
applications written in the C programming language and the (U)SIM in order to realize the co-operation set forth in 
TS 42.019 [4]. In particular, the API described herein provides the service of assembling proactive commands and 
disassembling the responses to these commands for the application programmer. 

Software tools, integrated software development environments and software management systems that may be used to 
create application programs are explicitly out of scope of the present document. 
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a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[I] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 
[2] 3GPP TS 31.1 1 1: "USIM Application Toolkit (US AT)". 

[3] 3GPP TS 23.048: "Security Mechanisms for the (U)SIM application toolkit; Stage 2". 
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Stage 1". 
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[8] 3GPP TS 1 1 . 14: "Specification of the SIM Application Toolkit for the Subscriber Identity Module 

- Mobile Equipment (SIM - ME) interface". 

[9] Tool Interface Standard (TIS) Executable and Linking Format Specification Version 1 .2. 

[10] SYSTEM V Apphcation Binary Interface, Edition 4.1. 

[II] 3GPP TS 51.01 1: "Specification of the Subscriber Identity Module - Mobile Equipment (SIM-ME) 
interface". 
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[13] 3GPP TS 31.1 15: "Secured packet structure for (U)SIM Toolkit appHcations". 
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[15] 3GPP TS 31.102: "Characteristics of the USIM Apphcation". 
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Definitions and abbreviations 



3.1 Definitions 

For the purposes of the present document, the following terms and definitions apply: 

application: computer program that defines and implements a useful domain-specific functionality 

The term may apply to the functionality itself, to the representation of the functionality in a programming language, or 

to the realization of the functionality as executable code. 

application executable: representation of an application as collection of executable codes 

application program: representation of an application in a programming language such as assembly language, C, Java, 
WML or XHTML 

Application Programming Interface (API): collection of entry points and data structures that an application program 
can access when translated into an application executable 

byte code: processor-independent representation of a basic computer operation such as "increment by one" that is 
executed by computer program called a byte code interpreter 

data structure: memory address that can be accessed by an application executable in order to read or write data 

entry point: memory address that can be branched to by an application executable in order to access functionality 

defined by an application-programming interface 

Depending on the software technology, an entry point is also called a subroutine, a function or a method. 

executable code: generic term for either byte code or native code 

framework: defines a set of Application Programming Interface (API) functions for developing applications and for 
providing system services to those applications 

loadfile: representation of an application executable that is transmitted from the terminal to the smart card operating 

system 

A loadfile typically includes information about the application executable in addition to the application executable 

itself 

native code: processor-dependent representation of a basic computer operation such as "increment by one" that is 
executed by the hardware circuitry of a computer's central processing unit 

toolkit application: uses the commands described in TS 3L1 1 1 and TS n.l4 

3.2 Abbreviations 

For the purpose of the present document, the following abbreviations apply: 

APDU Application Protocol Data Unit 

API Application Programming Interface 

CAT Card Application Toolkit 

CS Circuit Switched 

DCS Digital Cellular System 

DF Dedicated File 

DTMF Dual Tone Multiple Frequency 

EF Elementary File 

ELF Executable and Linkable Format 

FID File Identifier 

GSM Global System for Mobile communications 

ME Mobile Equipment 

NAA Network Access Application (SIM or USIM) 

OTA Over The Air 

SIM Subscriber Identity Module 
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SMS 
STK 

sw 

TAR 

TLV 

TPDU 

UICC 

URL 

USIM 

USSD 



Short Message Service 

SIM ToolKit 

Status Word 

Toolkit Application Reference 

Tag, Length, Value 

Transport Protocol Data Unit 

(not an acronym) 

Uniform Resource Locator 

Universal Subscriber Identity Module 

Unstructured Supplementary Services Data 



Description 



The (U)SIM Application consists of the following: 

APDU handlers for communicating with the ME; 

File system and file access control; 

Toolkit Framework that provides services to Toolkit apphcations. 

The present document describes the C programming language binding for the interface between the (U)SIM application 
and toolkit applications described in TS 42.019 [4]. This API allows application programmers using the C programming 
language to access functions and data described in TS 3L111 [2] and TS n.l4 [8], such that the (U)SIM-based 
applications and the services they implement can be developed and loaded onto ICCs. If required and supported by the 
underlying smart card technology, toolkit applications can be loaded or deleted remotely, after the card has been issued. 



4.1 



Overview 



The 'C -binding for (U)SIM API shall provide function calls for pro-active functions and transport functions. The figure 
below shows the interactions between a typical toolkit application (shown in blue) and the various functional blocks of 
the (U)SIM (shown in orange). The C-bindings for these APIs are presented in subclause 4.2. 
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4.2 Design Rationale and Upward Compatibility 

Some functions on the C SIM API take parameters that correspond to optional TLVs in TS 31.111 [2] and TS 1 1 . 14 [8] . 
If the actual parameter value passed to the function is NULL, the corresponding TLV is not passed to the ME; an 
example of an optional parameter is Catlconldentifier that corresponds to the ICON IDENTIFIER TLV. 

Some proactive commands have a very large number of optional TLVs, such as SETUP CALL. Therefore, this API 
offers two variants that address this aspect, CatSetupCall and CatSetupCallEx. The first function, CatSetupCall, takes 
as parameters everything that is necessary to issue a successful SETUP CALL proactive command (i.e. everything 
required to construct the mandatory TLVs as required by TS 31.111 [2] and TS 11.14 [8]) and also includes optional 
user interface TLVs (title and icon) for ease of use. 

The second function, CatSetupCallEx, takes a parameter block that can be extended in future versions of the present 
specification. The parameter block contains members that correspond to all mandatory and optional TLVs for the 
SETUP CALL proactive command. 

The reason for introducing the "...Ex" variants is threefold: 

Rather than extend the parameter list of a function to take a large number of optional parameters for each call, it 
is preferable to set up the parameters using named structure members before issuing the call to the function. 

If a future version of TS 3 1 . 1 1 1 [2] or TS 1 1 . 14 [8] extends the optional parameters for a proactive command, 
the corresponding parameter block can be extended to encompass these parameters without changing the 
function prototype. 

Any source code written for an older version of this C SIM API can be recompiled with a later version without 
change and will remain upwardly compatible at the source as long as the suggested coding standards are adhered 
to. 



4.3 Application Triggering 



The application-triggering portion of the SIM Toolkit Framework is responsible for the activation of toolkit 
applications, based on the APDU received by the card. 

The ME shall not be adversely affected by the presence of applications on the (U)ICC card. For instance a syntactically 
correct Envelope shall not result in an error status word in case of a failure of an application. The only application as 
seen by the ME is the (U)SIM application. As a result, a toolkit application may return an error, but this error will not 
be sent to the ME. 

The difference between an application and a toolkit application is that a toolkit application does not typically handle 
APDUs directly. It will handle higher-level messages. Furthermore the execution of a function could span over multiple 
APDUs, in particular, the proactive protocol commands. 

All the applications that have registered interest in the event are triggered in order of their priority. 

The current context is switched to the toolkit application. 
- A pending transaction is aborted. 

The current file context of the toolkit application is the MF. 

The current file context of the current selected application is unchanged. 
On termination of a toolkit application execution of CatExit(): 

The context switches back to the context of the current selected application, the NAA application. 

A pending toolkit application transaction is aborted. 
Here after are the events that can trigger a toolkit application: 
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EVENT_PROFILE_DOWNLOAD 

Upon reception of the Terminal Profile command by the (U)SIM, the Toolkit Framework stores the ME profile and then 
triggers the registered toolkit application that may want to change their registry. A toolkit application may not be able to 
issue a proactive command. 

EVENT_MENU_SELECTION,EVENT_MENU_SELECTION_HELP_REQUEST 

A toolkit application might be activated upon selection in the ME's menu by the user, or request help on this specific 
menu. 

In order to allow the user to choose in a menu, the Toolkit Framework shall have previously issued a SET UP MENU 
proactive command. When a toolkit application changes a menu entry of its registry object, the Toolkit Framework shall 
dynamically update the menu stored in the ME during the current card session. The SIM Toolkit Framework shall use 
the data of the EFsume file (TS 51.011 [11] and TS 31.102 [15]) when issuing the SET UP MENU proactive command. 

The positions of the toolkit application menu entries in the item list, the requested item identifiers and the associated 
limits (e.g. maximum length of item text string) are defined at the loading of the toolkit application. 

If at least one toolkit application registers to EVENT_MENU_SELECTION_HELP_REQUEST, the SET UP MENU 
proactive command sent by the Toolkit Framework shall indicate to the ME that help information is available. A toolkit 
application registered for one or more menu entries may be triggered by the event 

EVENT_MENU_SELECTION_HELP_REQUEST, even if it is not registered to this event. A toolkit appUcation 
registered for one or more menu entries should provide help information. 

EVENT_FORMA TTED_SMS_PP_ENV, EVENTJJNFORMA TTED_SMS_PP_ENV, 

EVENT_FORMATTED_SMS_PP_UPD,EVENT_UNFORMATTED_SMS_PP_UPD 

A toolkit application can be activated upon the reception of a short message. There are two ways for a card to receive an 
SMS: via the Envelope SMS-PP Data Download or the UpdateRecord EFsms instruction. 

The reception of the SMS by the toolkit application cannot be guaranteed for the Update Record EFsms instruction. 

The received SMS may be: 

formatted according to TS 23.048 [3] or an other protocol to identify explicitly the toolkit application for which 
the message is sent; 

unformatted or using a toolkit application specific protocol the Toolkit Framework will pass this data to all 
registered toolkit applications. 

EVENT_FORMA TTED_SMS_PP_ENV 

This event is triggered by an envelope APDU containing an SMS_DATADOWNLOAD BER TLV with an 
SMS_TPDU simple TLV according to TS 23.048 [3]. 

The Toolkit Framework shall: 

- verify the TS 23.048 [3] security of the SMS TPDU; 

trigger the toolkit application registered with the corresponding TAR defined at application loading; 

take the optional Application Data posted by the triggered toolkit application if present; 

secure and send the response packet. 

The toolkit application will only be triggered if the TAR is known and the security verified. Application data will also 
be deciphered. 

EVENT_UNFORMATTED_SMS_PP_ENV 

The registered toolkit apphcations will be triggered by this event and get the data transmitted in the APDU envelope 
SMS DATADOWNLOAD. 
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EVENT_FORMATTED_SMS_PP_UPD 

This event is triggered by Update Record EFsms with an SMS TP-UD field formatted according to TS 23.048 [3]. 

The Toolkit Framework shall: 

update the EFsms file with the data received, it is then up to the receiving toolkit application to change the SMS 
stored in the file (i.e. the toolkit application need to have access to the EFsms file); 

- verify the TS 23.048 [3] security of the SMS TPDU; 

convert the Update Record EFsms in a TLV List, an EnvelopeHandler; 

trigger the toolkit application registered with the corresponding TAR defined at application loading. 

EVENT_UNFORMATTED_SMS_PP_UPD 

The SIM Toolkit Framework will first update the EFsms file, convert the received APDU as described above, and then 
trigger all the registered toolkit applications. All of them may modify the content of EFsms (i.e. the toolkit applications 
need to have access to the EFsms file). 

EVENT_UNFORMATTED_SMS_CB 

When the ME receives a new cell broadcast message, the cell broadcast page may be passed to the card using the 
envelope command, e.g. the application may then read the message and extract a meaningful piece of information that 
could be displayed to the user, for instance. 

EVENT_CALL_CONTROL_BY_SIM 

When the NAA is in call control mode and when the user dials a number, this number is passed to the Toolkit 
Framework. Only one toolkit application can handle the answer to this command: call barred, modified or accepted. 

EVENT_EVENT_DOWNLOAD_MT_CALL,EVENT_EVENT_DOWNLOAD_CALL_CONNECTED, 

EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED,EVENT_EVENT_DOWNLOAD_LOCATION_STATUS, 

EVENT_EVENT_DOWNLOAD_USER_ACTIVITY,EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE, 

EVENT_EVENT_DOWNLOAD_CARD_READER_STATUS 

The toolkit application will be triggered by the registered event download trigger, upon reception of the corresponding 
Envelope command. In order to allow the toolkit application to be triggered by these events, the Toolkit Framework 
shall have previously issued a SET UP EVENT LIST proactive command. When a toolkit application changes one or 
more of these requested events of its registry, the Toolkit Framework shall dynamically update the event list stored in 
the ME during the current card session. 

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM 

Before sending an SMS MO entered by the user, the SMS is submitted to the Toolkit framework. Only one toolkit 
application can register to this event. 

EVENT_TIMER_EXPIRATION 

This event is registered when the application executes a successful Toolkit CatGetTimer(). The toolkit application can 
then manage this (these) timer(s), and it will be triggered at the reception of the APDU Envelope TIMER 
EXPIRATION. The Toolkit Framework shall reply busy to this Envelope APDU if it cannot guaranty to trigger the 
corresponding toolkit application. 

EVENT_UNRECOGNIZED_ENVELOPE 

The application registered to this event shall be triggered by the framework if the BER-TLV tag contained in the 
ENVELOPE APDU is not defined in the associated release of TS 31.111 [2] and TS 1 1 . 14 [8] and if no corresponding 
constant is defined in the list of the ToolkitConstants interface. By providing the means to transfer an arbitrary block of 
data, the Unrecognized Envelope Event will allow a toolkit application to handle the evolution of the specifications 
TS 31.111 [2] andTS 11.14 [8]. 
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EVENT_STA TUS_COMMAND 

At reception of a STATUS APDU command, the SIM Toolkit Framework shall trigger the registered toolkit 
application. 

A range of events is reserved for experimental and proprietary usage (from -128 to -1). As the definition of these events 
is not standardized, the use of these events may make the toolkit application behave differently on different platforms. 

The toolkit application shall be triggered for the registered events upon reception, and shall be able to access to the data 
associated to the event using OpenEnvelope() or the low-level functions. 

The order of triggering the toolkit application shall follow the priority level of each toolkit application defined at its 
loading. If several toolkit applications have the same priority level, the last loaded toolkit application takes precedence. 



4.4 Proactive command handling 



The (U)SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the network access 
application and the Toolkit Framework. The toolkit application shall not handle those events. 

The network access application and the Toolkit Framework shall handle the transmission of the proactive command to 
the ME, and the reception of the response. The Toolkit Framework will then return in the toolkit application just after 
the proactive command. It shall then provide to the toolkit application the values as indicated in the function 
parameters. It also provides the raw return information so that the toolkit application can analyse the response. 

The proactive command is sent to the ME as defined and constructed by the toolkit library without any check of the 
Toolkit Framework. 

The toolkit application shall not issue the following proactive commands: SET UP MENU, SET UP EVENT LIST, 
POLL INTERVAL, POLLING OFF; as those are system proactive commands that will affect the services of the Toolkit 
Framework. 



4.5 Application Loading 



Applications compliant to the present document are represented for loading as loadfiles in the Executable and Linkable 
Format (ELF) described in Tool Interface Standard (TIS) Executable and Linking Format Specification [9] and 
SYSTEM V Application Binary Interface [10]. The application executable in the ELF loadfile may be either native 
code or byte code that has been created through a process of compiling the representation of the application program in 
the C programming language. 

The e_machine entry in the ELF header is set to according to the table in annex A and indicates the architecture for 
which the application executable in the loadfile has been prepared. 

Coding for other processors, processor instruction set extensions and byte code interpreters will be defined as needed 
processor-specific or interpreter-specific supplements to SYSTEM V Application Binary Interface [10] may also be 
provided as needed. 

Loadfile linkers, loaders and installers, whether on-card or off -card, return an error condition if the application 
representation in the loadfile cannot be accommodated or if resources requested by the application are not available. 

The over-the-air application loading mechanism, protocol and application life cycle are defined in TS 23.028 [3]. 



5 'C'-language binding for (U)SIM API 

5.1 Overview 

This subclause presents the 'C'-language binding to (U)SIM API. It is divided into sections as follows: 
Toolkit application entry and exit. 
Man-Machine Interface. 
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Timers. 

Supplementary card reader. 

UICC file store access. 

- Registry. 
Miscellaneous. 
Low-level functions. 
Network services. 

- Supporting data types. 

For each function, the prototype is given followed by a table describing the parameters and whether they are input [in] 
or output [out] parameters. There is explanatory text which explains the function's purpose and whether it is a proactive 
command or not. 



5.2 Toolkit Application Functions 



Toolkit applications will start by executing the application-defined function main. There are no arguments to main, nor 
are there any return results. The application can find out why it was invoked using the CatGetFrameworkEventt 
function. The Framework events that can cause an application to be invoked can be split into the following groups: 

Command monitoring. 

ME monitor events. 

Application lifecycle change. 

Command monitoring enables applications to be invoked when the framework receives commands from the ME. 
Currently supported commands that can be monitored are: 

TERMINAL PROFILE: monitoring this command enables an application to be invoked when the ME is 
powered on. 

STATUS: monitoring this command enables an application to be invoked when the ME polls for proactive 
commands. 

ENVELOPE: monitoring this command enables the application to be informed of specific envelope type arrival 
for example call control envelopes can be monitored. 

ME monitor events are events that the framework can ask the ME to monitor; for example an event can be sent on call 
connection. ME monitored events are delivered to the application in the EVENT DOWNLOAD envelope as received 
from the ME. 

The application lifecycle event enables the framework to invoke an application when the application status has changed. 
This is mainly to enable an application to be run at installation time so that it can set up its registry entries. The details 
of the application lifecycle events are provided in TS 3L116 [14]. 

5.2.1 main 

void 

main (void) ; 

The main function is the application entry point. The apphcation should not return from main; it must call the CatExit 
function. 

An example main function is given below: 

void main (void) 
{ 

switch (CatGetFrameworkEvent ( ) ) 
{ 
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case EVENT_APPLICATION_LIFECYCLE_INSTALL : 
// set up registry for this application 

CatSetMenuString( 

CatNotifyOnEnvelope (SMS_PP_DOWNLOAD_TAG, 1) ; 
CatNotifyOnEvent (CARD_READER_STATUS, 1) ; 
break; 
case EVENT_ENVELOPE_COMMAND : 
{ 

BYTE length; 

switch (CatOpenEnvelope (Slength) ) 
{ 

case MENU_SELECTION_TAG: 

// search for help request 

break; 
case SMS_PP_DOWNLOAD_TAG : 

break; 
case EVENT_DOWNLOAD_TAG : 

// search for card reader status event 

break; 
default : 

CatExit ; 



break; 
default : 
CatExit ; 
break; 



CatExit I 



5.2.2 CatGetFrameworkEvent 

CatFrameworkEventType 
CatGetFrameworkEvent (void) ; 



RETURN 



Framework event type that caused the application to run; see 
CatFrameworl<EventTvpe for details. 



5.2.3 CatExit 

void 

CatExit (void) ; 



CatExit causes the application to terminate execution and return control to the framework. When the application is 
restarted, it enters at main. 



5.3 Registry 



The menu entry(ies) of the application, together with the set of framework events that the apphcation is interested in, 
may be registered using the functions defined in this subclause. 



5.3.1 CatSetlVlenuString 



void 

CatSetMenuString (BYTE MenuID, 

BYTE MenuStringLength, const void *MenuString, 
const Catlconldentifier * Iconldentifier, 

BYTE HelpAvailable, 
BYTE NextAction) ; 
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MenulD 


[in] 


The menu ID by whicli this entry is l<nown. 


MenuStringLength 


[in] 


The length, in bytes, of MenuString. 

The menu entry to be placed in the registry. If MenuString is NULL or 


MenuString 


[in] 


MenuStringLength is zero, any existing menu entry associated with MenulD 

is removed and is not displayed by the ME. 

Ootional icon identifier; see Catlconldentifierfor member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier is 
sent to the ME. 


HelpAvailable 


[in] 


If non zero the application can supply help. 


NextAction 


[in] 


The (optional) next action value 



CatSetMenuString allows the application to define a menu entry together with an icon. A non-zero value can be 
supplied if a next action indicator is required. This function will implicitly request that the application is notified of 
menu selection envelopes i.e. there is no requirement to call the CatNotifiyOnEnvelope function. An application can 
have several menu entries and must examine the menu selection envelope to decide which menu selection caused it to 
be invoked. 

The ordering of menu entries within a menu presented by the ME is based on increasing integer values of identifiers 
selected by the application. Note that any application's menu item ordering may be further overridden by an external 
source, e.g. card issuer, via a request to the SIM Toolkit framework this mechanism is beyond the scope of the present 
document. 

5.3.2 CatNotifyOnFrameworkEvent 

void 

CatNotifyOnFrameworkEvent (CatFrameworkEventType Event, BYTE Enabled); 



^ . ,. , A framework event the application is interested in, see 

^ ' CatFrameworkEventType for details. 

If non-zero the framework event is monitored otherwise the framework event 
isn't monitored. By default only application lifecycle events are monitored. 



Enabled [in] 



CatNotifyOnFrameworkEvent enables the application to add/remove a framework event to/from the set of framework 
events that it is interested in. 

5.3.3 CatNotifyOnEnvelope 

void 

CatNotifyOnEnvelope (CatEnvelopeTagType Tag, BYTE Enabled); 



Tag [in] 



The particular envelope type to monitor; see CatEnvelopeTaqTvpe for 
details. 



Enahlpd Finl '^ non-zero the envelope type is monitored otherwise the envelope type isn't 

^ ' monitored. 



CatNotifyOnEnvelope enables the application to add/remove an envelope monitoring event to/from the set of the 
envelope monitoring events it is interested in. Note that the monitoring of MENU SELECTION, TIMER EXPIRATION 
and EVENT DOWNLOAD envelopes is handled by the framework. 

5.3.4 CatNotifyOn Event 

void 

CatNotifyOnEvent (CatEventType EventType, BYTE Enabled); 



EventType [in] The particular event type to monitor; see CatEventType for details. 
Enabled [in] If non-zero the event type is monitored otherwise the event isn't monitored. 



CatNotifyOnEvent enables the application to add/remove an ME monitored event to/from the set of ME monitored 
events it is interested in. 
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5.4 Man-Machine Interface 
5.4.1 CatAddltem 

void 

CatAddltem (BYTE ItemTextLength, const void *ItemText, BYTE Itemldentifier) ; 



ItemTextLength 


[in] 


The length in bytes of the following ItemText f\e\6. 


ItemText 


[in] 


Text associated with item. 

Specifies a unique identifier to be associated with this selection. This value is 


Itemldentifier 


[in] 


returned in the Selectedltem parameter of CatSelectltem if this item is 
selected from the menu. 



CatAddltem adds an item to a list for the user to select. See CatSelectltem below for details on the construction of a 
display list. 

5.4.2 CatSelectltem 

void 

CatSelectltem (BYTE TitleLength, const void *Title, 
CatSelectltemOptions Options) ; 



TitleLength [in] The length in bytes of Title. 

Title [in] Title of the list of choices. 

Options [in] Acceptable values for this parameter are listed in CatSelectltemOptions. 



CatSelectltem initiates the construction of a list of items to be displayed to the user and from which the user is expected 
to select exactly one entry. After CatSelectltem has been called, entries are added to the list one at a time using the 
CatAddltem entry point above. When all items have been added to the list, the list is sent to the ME using the 
CatEndSelectltem entry point below. CatEndSelectltem causes the list to be displayed and returns to the caller the item 
selected. 

5.4.3 CatEndSelectltem 

CatGeneralResult 

CatEndSelectltem (BYTE * Selectedltem, 

const Catlconldentifier * Iconldentifier) ; 



Selectedltem [out] Index of item selected by user. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier is 

sent to the ME. 
RETURN The GeneralResult code of the SELECT ITEM proactive command. 



CatEndSelectltem issues the proactive command SELECT ITEM that displays on the ME a list of items for the user to 
choose from. The terminal response is parsed and if successful the Selectedltem parameter is set to the index of the item 
chosen. See CatSelectltem above for details on the construction of a display list. 

5.4.4 CatDlsplayText 

CatGeneralResult 

CatDlsplayText (CatDCSValue TextDCS, BYTE TextLength, const void *Text, 

CatDisplayTextOpt ions Text Options, 

CatTextFormat TextFormat , 

CatForegroundColor ForegroundColour , 

CatBackgroundColour BackgroundColour , 

const Catlconldentifier * Iconldentifier, 

BYTE IiumediateResponse) ; 
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TextDCS 

TextLength 

Text 

TextOptions 

TextFormat 

ForegroundColour 

BackgroundColour 

Iconldentifier 



ImmediateResponse 
RETURN 



[inj 

[in] 
[in] 
[in] 
[in] 
[in] 
[in] 

[in] 



in 



The data coding sclieme for Text. Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Text 

String to display on ME. 

Acceptable values for this parameter are listed in CatPisplavTextOptions . 

Format of text; e.g. bold, italic, etc. 

Foreground colour of text; i.e. colour of the letters. 

Background colour of text; i.e. colour filled in behind the letters. 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier \s NULL or if Icon Identifier. Uselcon is zero, no icon identifier 

is sent to the ME. 

True-program continues execution as soon as ME receives instruction. 

False-program waits until text is cleared on the ME before continuing, and 

the Immediate Response TLV is not passed to the ME. 

The GeneralResult code of the DISPLAY TEXT proactive command. 



5.4.5 CatGetlnKey 



CatGeneralResult 

CatGetlnKey (CatDCSValue TitleDCS, BYTE TitleLength, const void *Title, 

CatGetlnKeyOptions Options, 

const Catlconldentifier * Iconldentifier, 

CatDCSValue *DCSOut, void *KeyOut) ; 



TitleDCS 

TitleLength 

Title 

Options 

Iconldentifier 



DcsOut 

KeyOut 
RETURN 



[inJ 

[in] 
[in] 
[In] 

[inl 



[out] 
[out] 



The data-coding scheme for Title. Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Title. 

String to display on ME. 

Acceptable values for this parameter are listed in CatGetlnKeyOptions . 

Optional icon identifier; see Catlconldentifier for member details. If 

Icon Identifier \s NULL or if Iconldentifier Uselcon is zero, no icon identifier is 

sent to the ME. 

The packing type of the returned key. This parameter is set to one of the 

values listed in CatDCSValue . 

The key pressed. 

The GeneralResult code of the GET INKEY proactive command. 



CatGetlnKey issues the proactive command GET INKEY. The terminal response is parsed and if successful the 
DCSOut and KeyOut parameters are updated. 



5.4.6 CatGetlnput 



CatGeneralResult 

CatGetlnput (CatDCSValue TitleDCS, BYTE TitleLength, const void *Title, 
CatGetlnputOptions Options, 

CatDCSValue DefaultReplyDCS, 

BYTE DefaultReplyLength, const void *DefaultReply, 

BYTE MinimumResponseLength, 

BYTE MaximumResponseLength, 

const Catlconldentifier * Iconldentifier , 

CatDCSValue *MsgOutDCS, BYTE *MsgOutLength, void *MsgOut) ; 
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TitleDCS 


[in] 


TitleLength 


[in] 


Title 


fin] 


Options 


[In] 


DefauitRepiyDCS 


[in] 


DefauitRepiyLengtti 


[in] 


DefauitRepiy 


[in] 


l\/linimumResponseLengtli 


[in] 


MaximumResponseLengtti 


[in] 


Iconldentifier 


[in] 


MsgOutDCS 


[out] 


MsgOutLengtli 


[out] 


MsgOut 


[out] 


RETURN 





The data-coding sclieme for Titie. Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Titie. 

String to display on ME while waiting for the user to press a key. 

Acceptable values for this parameter are listed in CatGetlnputOptions . 

The data-coding scheme for DefauitRepiy. Acceptable values for this 

parameter are listed in CatDCSValue . 

The length in bytes of DefauitRepiy. 

Default response string; use NULL for "no reply"-no Default Reply tag 

length value (TLV) is sent to the ME. 

Minimum allowed length for the response, in either characters or digits. 

Maximum allowed length for the response, in either characters or digits. 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier \s NULL or if iconldentifier.Uselcon is zero, no icon identifier 

is sent to the ME. 

Packing type of the returned data. This parameter is set to one of the 

values listed in CatDCSValue . 

Length of the returned message in bytes. 

A pointer to where the returned string or message is placed. 

The GeneralResult code of the GET INPUT proactive command. 



CatGetlnput issues the proactive command GET INPUT. The terminal response is parsed and if successful 
MsgOutDCS, MsgOutLengtli, MsgOut parameters are updated. 



5.4.7 CatSetupldleModeText 



CatGeneralResult 

CatSetupldleModeText (CatDCSValue TextDCS, BYTE TextLength, const void *Text, 
const Catlconldentifier * Iconldentifier) ; 



TextDCS 



[in] 



TextLengtIi 
Text 


[in] 
[In] 


Iconldentifier 


[in] 



The data-coding scheme for Text Acceptable values for this parameter are 

listed in CatDCSValue . 

The length in bytes of Text. 

String to display while ME is idle. 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier \s NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the SETUP IDLE MODE TEXT proactive 

command. 



CatSetupldleModeText issues the proactive command SET UP IDLE MODE TEXT that sets the ME's default text 
string. 



5.4.8 CatPlayTone 



CatGeneralResult 

CatPlayTone (BYTE TextLength, const void *Text, 
CatTone Tone, 

CatTimeUnit Units, BYTE Duration, 
const Catlconldentifier * Iconldentifier) 



TextLength} 
Text 

Tone 

Units 
Duration 

Iconldentifier 

RETURN 



[in] 
[In] 

[in] 

[in] 
[in] 

[in] 



The length in bytes of the string Texf to display on the ME. 

String to display on ME while sound is being played. 

Specifies tone to play. Acceptable values for this parameter are listed in 

CatTone . 

Unit of time specified for duration parameter. Acceptable values for this 

parameter are listed in CatTimeUnit . 

Amount of time to play the tone, in units specified in the Units parameter 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier \s NULL or if Icon Identifier Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the PLAY TONE proactive command. 
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CatPlayTone issues the proactive command PLAY TONE. 

5.5 Timers 

5.5.1 CatGetTimer 

BYTE 

CatGetTimer (void) ; 

I RETURN The identifier of the timer. | 

CatGetTimer returns the ID of a timer that is not currently in use. If no timer is available, this function returns zero. 
Timer identifiers are assigned by the framework. 

5.5.2 CatFreeTimer 

void 

CatFreeTimer (BYTE TlmerlD) ; 



TimerlD [in] ID of timer to free; obtained from CatGetTimer. 



CatFreeTimer frees the handle to the specified timer, making it available for the next request. It is not a proactive 
command. No information is passed to the ME by this function. 

5.5.3 CatStartTimer 

void 

CatStartTimer (BYTE TlmerlD, CatTimerValue *TlmerValue) ; 



TimerlD [in] ID of the timer to initialize; obtained from CatGetTimer . 

_. ,, , p. , Initial value of the timer. The value is specified in a structure of type 

TimerValue [in] ^ .-^. ., , 

'■ ' CatTimerValue . 

RETURN The GeneralResult code of the TIMER MANAGEMENT proactive command. 



CatStartTimer issues a proactive TIMER MANAGEMENT command to initiaUze a timer to the parameter values. 

5.5.4 CatGetTimerValue 

void 

CatGetTimerValue (BYTE TlmerlD, CatTimerValue * TimerValue) ; 



TimerlD [in] ID of the timer from which to obtain values; obtained from CatGetTimer 

^, ,, , , ,, The time remaining to run of timer TimerlD. The value is returned in a 

TimerVaue [out] , , , , /-. j-r- \ # i 

^ ' structure of type CatTimerValue . 

RETURN The GeneralResult code of the TIMER MANAGEMENT proactive command. 



CatGetTimerValue issues a proactive TIMER MANAGEMENT command to obtain the timer's current value. 

5.6 Supplementary Card Reader Management 

These functions access the supplementary card-reader on a dual-slot ME. 
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5.6.1 CatPowerOnCard 

CatGeneralResult 

CatPowerOnCard (CatDevice DevicelD, BYTE *ATRLength, void *ATR) ; 



_ . ,„ ,. , The device to power on. An acceptable value for this parameter is a card 

DevicelD in ^ ^ ■ , . ^,. r^*^^■ 

reader device selected from CatDevice . 

, T-o, .^ r- / .1 Size of the ATR buffer on input and the umber of bytes returned by the card 

ATRLength in/out tu A-m * * 

" ^ ' as the ATR on output. 

ATR [out] Pointer to where answer to reset (ATR) will be stored. 

RETURN The GeneralResult code of the POWER ON CARD proactive command. 



CatPowerOnCard issues the proactive command POWER ON CARD that powers on a supplementary card reader. The 
terminal response is parsed and if successful the ATR and ATRLength parameters are. 

5.6.2 CatPowerOffCard 

CatGeneralResult 

CatPowerOffCard (CatDevice DevicelD) ; 



^ The device to power off. An acceptable value for this parameter is a card 

^ ' reader device selected from CatDevice . 

RETURN The GeneralResult code of the POWER OFF CARD proactive command. 



CatPowerOffCard issues the proactive command POWER OFF CARD that turns off the supplementary card reader. 

5.6.3 CatPerformCardAPDU 

CatGeneralResult 

CatPerformCardAPDU (CatDevice DevicelD, 

BYTE CAPDULength, const void *CAPDU, 

BYTE *RAPDULength, void *RAPDU) } 



DevicelD 


[in] 


CAPDU 


[in] 


CAPDULength 


[in] 


RAPDU 


[out] 


RAPDULength 


[out] 


RETURN 





The device to send the command APDU (C-APDU) to. An acceptable value 
for this parameter is a card reader device selected from CatDevice . 
Pointer to the command C-APDU to be sent to the additional card 

device. 

The number of bytes in the C-APDU. 

Pointer to the buffer that will contain the response APDU (R-APDU) returned 

by the card in the additional card reader. You must allocate enough space to 

hold the R-APDU sent by the card. 

The number of bytes returned by the card in the additional card reader. 

The GeneralResult code of the PERFORM CARD APDU proactive 

command. 



CatPerformCardAPDU issues the proactive command PERFORM CARD APDU that sends application program data 
units (APDU) to the supplementary card reader. The terminal response is parsed and if successful the RAPDU and 
RAPDULength parameters are updated. 

5.6.4 CatGetReaderStatus 

CatGeneralResult 

CatGetReaderStatus (CatDevice DevicelD, CatReaderStatusOptions Options, 

BYTE *Status) ; 
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DevicelD [in 

Options [in 



Device to detect status of. An acceptable value for this parameter is a card reader 
device selected from CatPevice. 



Selects what type of status information to return. An acceptable value for this 
parameter is selected from CatGetReaderStatusOptions . 

Status [out] Status of additional card reader. 

RETURN The GeneralResult code of the GET READER STATUS proactive command. 



CatGetReaderStatus issues the proactive command GET READER STATUS that retrieves the status of the additional 
card readers on the ME. The terminal response is parsed and if successful the Status parameter is updated. 

5.7 Dice File Store Access 

The abstract type FID is used to denote the file and a set of pre-processor macros are defined that enumerate all of the 
standard files of a NAA file store. A FID could be implemented as an unsigned 16-bit number as follows; 

typedef unsigned short FID; 
♦define FID_MF 0x3F00 

The starting file-context of a toolkit application is the MF. When a oolkit application exits, the file-context is lost. 

The Access Control privileges of the application are granted during installation according to the level of trust. When an 
application requests access to UICC or operator specific files, the Toolkit Framework checks if this access is allowed by 
examination of the file control information stored on the card. If access is granted the Toolkit Framework will process 
the access request, if access is not granted, an appropriate status word will be returned. 

Contents and coding of the file(s) containing access control information are defined in ETSI TS 102 221 [12]. 

All UICC functions return the status bytes according to ETSI TS 102 221 [12], where 90 00 represents success. 

5.7.1 CatSelect 

UINT16 

CatSelect (CatFID Fileldentifier, CatFileStatus *Status)} 



Fileldentifier [in] The file to select. 

„ P , Usefullnformatlon about the directory or file if It Is successfully 

selected. 
The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatSelect selects the specified file as the current working file. 

5.7.2 CatStatus 

UINT16 

CatStatus (CatFileStatus *Status)} 



NumBytes [out] The number of bytes written. 

Status [out] The status of the currently selected file. 

The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatStatus returns the file status of the currently selected file as specified in ETSI TS 102 221 [12]. 
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5.7.3 CatGetCHVStatus 

void 

CatGetCHVStatus (BYTE CHVStatus [4] ) ; 



ruyqt^t,.^ rni iti Updates the CHVStatus array with the statusof CHV1 , CHV2, 

^ ^ UNBL0CKCHV1 , and UNBL0CKCHV2 with CHV1 at array element zero. 



CatGetCHVStatus returns the current CHV status values. The format of the returned bytes is specified in 
ETSITS 102 221 [12]. 



5.7.4 CatReadBinary 



UINT16 
CatReadBinary 


(DWORD 
DWORD 
void < 


Offset, 
* NumBytes 
"Buffer) ; 


Offset 

NumBytes 

Buffer 

RETURN 




[in] 

[in/out] 

[out] 



The offset into the file. 

The number of bytes to be read on input and the actual number read on 

output 

The buffer into which the data is written. 

The returned 16-bit unsigned value is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatReadBinary reads NumBytes from position Offset in the currently selected file into Buffer. 

5.7.5 CatUpdateBinary 

UINT16 

CatUpdateBinary (DWORD Offset, 

DWORD NumBytes, 
const void *Buffer) ; 



Offset 


[in] 


The offset into the file. 


NumBytes 


[In] 


The number of bytes to write. 


Buffer 


[In] 


The buffer containing the data to write to the file. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



CatUpdateBinary writes NumBytes contained in Buffer to position Offset in the currently selected file. 

5.7.6 CatReadRecord 

UINT16 

CatReadRecord (DWORD RecordNumber, 

CatRecordAccessMode Mode, 

DWORD Offset, DWORD * NumBytes, 

void *Buffer) ; 
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RecordNumber 


[in] 


Mode 


[in] 


Offset 


[in] 


NumBytes 


[in/out] 


Buffer 


[out] 


RETURN 





The record number from which to read when Mode is ABSOLUTE or 

otherwise. 

Indication of whicli record is to be read; viz. NEXT, PREVIOUS, CURRENT 

or ABSOLUTE. 

The offset into the record. 

The number of bytes to be read from the record on input and the number of 

bytes actually read on output 

The buffer into which the data is read. 

The returned 16-bit unsigned value is a concatenation of the SW 

response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatReadRecord reads NumBytes from the record RecordNumber of the currently selected file into Buffer. 

5.7.7 CatUpdateRecord 

UINT16 

CatUpdateRecord (DWORD RecordNumber, 

CatRecordAccessMode Mode, 

DWORD Offset, DWORD NumBytes, 

const void *Buffer) ; 



RecordNumber 


[in] 


The record number to which to write when Mode is ABSOLUTE or 

otherwise 


Mode 


[in] 


Indication of which record is to be read; viz. NEXT, PREVIOUS, CURRENT 
or ABSOLUTE. 


Offset 


[in] 


The offset into the record. 


NumBytes 


[in] 


The number of bytes to write into the record. 


Buffer 


[out] 


The buffer containing the data to write to the record. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



CatUpdateRecord writes NumBytes into the record RecordNumber of the currently selected file from Buffer. 

5.7.8 CatSearch 

UINT16 

CatSearch (CatSearchModes Mode, 

DWORD Offset, DWORD PatternLength, 

const void *Pattern) ; 







Defines the seek method, One of 






SEEK FROM BEGINNING FORWARD, 


Mode 


[in] 


SEEK FROM END BACKWARD, 

SEEK FROM NEXT FORWARD, 

SEEK FROM PREVIOUS BACKWARD 


Offset 


[in] 


The offset into the record at which to being pattern matching. 


PatternLength 


[in] 


The size in bytes of the pattern to search for. 


Pattern 


[in] 


The buffer containing the pattern to search for. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



CatSearch searches records in the currently selected file starting at Offset for the pattern of length PatternLength 
contained in Pattern. If the pattern is found the current record is set appropriately. 

5.7.9 Catlncrease 

UINT16 

Catlncrease (DWORD Increment, 

DWORD *Value) ; 
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Increment 


[in] 


The value to increase by. 


Value 


[out] 


The new value. 
The returned 16-bit unsigned value is a concatenation of the SW 


RETURN 




response bytes with SW1 as the high byte and SW2 as the low byte, so 
a successful execution would return 0x9000. 



Catlncrease adds Increment to the current record of the selected cylic file and returns the new Value. The most 
significant byte of Increment is ignored. 

5.7.10 Catlnvalidate 

UINT16 

Catlnvalidate (void) ; 



The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



Catlnvalidate invalidates the selected file. 

5.7.11 CatRehabilitate 

UINT16 

CatRehabilitate (void) ; 



The returned 16-bit unsigned value is a concatenation of the SW 
RETURN response bytes with SW1 as the high byte and SW2 as the low byte, so 

a successful execution would return 0x9000. 



CatRehabilitate rehabilitates the selected file. 



5.8 Miscellaneous 



5.8.1 CatGetTerminalProfile 

void 

CatGetTerminalProfile (BYTE *ProflleOutLength, BYTE *Proflle) i 



ProfileOutLength [out] The number of bytes written to Profile. 

Profile [out] Tlie address at wiiicli tiie terminal profile is written. 



CatGetTerminalProfile returns the stored terminal profile in Profile. 

5.8.2 CatMoreTime 

CatGeneralResult 
CatMoreTime (void) ; 



I RETURN The GeneralResult code of the MORE TIME proactive command. \ 

CatMoreTime issues the proactive command MORE TIME to the ME that it needs more time to process an application. 

5.8.3 CatPollingOff 

CatGeneralResult 
CatPollingOff (void) ; 
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I RETURN The GeneralResult code of the POLLING OFF proactive command. \ 

CatPollingOff issues the proactive command POLLING OFF that disables proactive polling; this essentially turns off 
CatPollInterval. 

5.8.4 CatPollInterval 

CatGeneralResult 

CatPollInterval (CatTimeUnit Unit, BYTE Interval, 

CatTimelnterval *ActualIntervalOut) ; 



Unit 


[in] 


Interval 


[in] 


RETURN 





Desired time interval. Acceptable values for this parameter are listed in 
CatTimeUnit . 
Interval in units. 

Response from ME negotiating the interval. This may or may not be the 
same as Unit and Interval. The value returned is in a structure of type 
CatTimelnterval . 
The GeneralResult code of the POLL INTERVAL proactive command. 



CatPollInterval issues the proactive command POLL INTERVAL that requests the ME to set a time interval between 
status application program data units (APDU) that the ME sends to the UICC. The ME responds with a time interval of 
its own that most closely matches the application programming interface (API) request. 

Polling can be disabled by using CatPollingOjf. 

5.8.5 CatRefresh 

CatGeneralResult 

CatRefresh (CatRefreshOptions Options) ; 

CatGeneralResult 

CatRefreshWithFileList (CatRefreshOptions Options, 

BYTE FlleLlstLength, 

const void *FlleLlst) ; 



Options [in] 



FileListLength 


[in] 


FileList 


[in] 


RETURN 





Informs the IVIE of what needs refreshing. Acceptable values for this 

parameter are listed in CatRefreshOptions . 

The length, in bytes, of FileList 

The file identifiers of the files that have changed. 

The GeneralResult code of the REFRESH proactive command. 



CatRefresh issues the proactive command REFRESH that informs ME that the NAA has changed configuration due to 
UICC activity (such as an application running). 

5.8.6 CatLanguageNotification 

void 

CatLanguageNotification (CatLanguageNotificationOptions Options, 

const void *Language) ; 



Language options. An acceptable value for this parameter is a card reader 
device selected from CatLanguageNotificationOptions . 

The 2-character language code as defined by ISO 639 [5], encoded 
using SMS default 7-bit coded alphabet as defined by TS 23.038 [6]. 
Dir-r/ /oa; The GonoralResult code of the LANGUAGE NOTIFICATION proactive 

RETURN command. 



Options [in] 

Language [in] 



CatLanguageNotification issues the proactive command LANGUAGE NOTIFICATION that notifies the ME about the 
language currently used for any text string within proactive commands or envelope command responses. 
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5.8.7 CatLaunchBrowser 

CatGeneralResult 

CatLaunchBrowser (CatLaunchBrowserOptions Options, 

BYTE TitleLength, const void *Title, 

BYTE URLLength, const void *URL, 

const Catlconldentifier * Iconldentifier) ; 



Options 

TitleLength 
Title 

URLLength 
URL 

Iconldentifier 



RETURN 



[in] 

[in] 
[in] 
[in] 
[in] 

[in] 



Options used to launch the browser. Acceptable values for this parameter 

are listed in CatLaunchBrowserOptions . 

The length in bytes of the string Title 

String to display on the ME during the user confirmation phase. 

The length in bytes of URL. 

The URL to open the browser at. 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier 

is sent to the ME. 

The GeneralResult code of the LAUNCH BROWSER proactive 

command. 



CatLaunchBrowser and CatLaunchBrowserEx issue the proactive command LAUNCH BROWSER that launches a 
browser on the ME. 

CatGeneralResult 

CatLaunchBrowserEx (const CatLaunchBrowserExParams *params) ; 

The Structure CatLaunchBrowserExParams has the following members: 

typedef struct 
{ 

// Mandatory fields 

CatLaunchBrowserOptions Options, 

BYTE URLLength; 

const void *URL; 

// Optional fields 

BYTE BrowserldentityLength; 

const void *BrowserIdentity; 

BYTE BearerLength; 

const BYTE *Bearer; 

BYTE NumProvisioningFileRef erences; 

BYTE *ProvisioningFileRef erenceLengths; 

const BYTE **ProvisioningFileRef erences; 

BYTE GatewayProxyldLength; 

const void * GatewayProxyld; 

CatAlphaString Title; 

Catlconldentifier Iconldentifier; 
} CatLaunchBrowerExParams; 

with the following members: 



URLLength 

URL 

Bro wserlden tity Length 

Browserldentity 

BearerLength 

Bearer 

NumProvisioningFileReferences 
ProvisioningFileReferenceLengths 
ProvisioningFileReferences 
GatewayProxyldLength 

GatewayProxyld 

Title 

Iconldentifier 



The length in bytes of URL. 
The URL to open the browser at. 
Length in bytes of Browserldentity. 

The browser identity. If Browserldentity is NULL, no BROWSER 
IDENTITY TL V is sent to the ME. 
Length in bytes of Bearer 

The list of bearers in order of priority requested. The type CatBearer 
defines the values acceptable. If Bearer \s NULL, no BEARER TLV is 
sent to the ME. 

The number of Provisioning File References. 
A pointer to the array of Provisioning File References lengths. 
A pointer to the array of Provisioning File References. 
Length in bytes of GatewayProxyld. 

The gateway or proxy identity. If GatewayProxyld \s NULL, no TEXT 
STRING TLV describing the gateway/proxy is sent to the ME. 
String to display on the ME; see CatAlphaString . 
Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier. Uselcon is zero, no icon identifier is sent to the ME. 
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5.9 Low-level Interface 

This subclause presents a low-level programming interface that allows you to: 

Construct proactive commands and send them to the ME. 

Access the terminal response from the ME. 

Search the terminal response and contents of envelopes for specified TLVs. 

Unpack the contents of envelopes from the ME and send responses. 

These functions are provided so that functionality that is not provided in the high level API is still accessible. All of 
these functions work on a single data buffer that has a single data pointer and can only be accessed sequentially. The 
high-level proactive functions may make use of the data buffer so consequently the high-level proactive functions 
should not be used whilst using the low-level functions. 

5.9.1 CatResetBuffer 

void 

CatResetBuffer (void) ; 

This function resets the data pointer to the beginning of the buffer. 

5.9.2 CatStartProactiveCommand 

void 

CatStartProactiveCommand (BYTE Command, 

BYTE Options, 

BYTE To) ; 



Command [in] Command byte of proactive command. 
Options [in] Command options of proactive command. 
To [in] The destination device identity. 



CatStartProactiveCommand resets the data pointer and starts the construction of a proactive command by writing the 
command tag, command details and device identities to the data buffer. The data pointer is left pointing after the device 
identities so that proactive command specific data can be written. 

5.9.3 CatSendProactiveCommand 

CatGeneralResult 
CatSendProactiveCommand (BYTE *Length) ; 



Lengtii [out] Pointer that is updated with the length of the terminal response 
RETURN The general result byte of the terminal response 



CatSendProactiveCommand sends the contents of the data buffer as a proactive command and updates the data buffer 
with the terminal response. The general result byte of the terminal response is returned by this function. The length of 
the terminal response is written to *Length. The data pointer is set to point to the additional information of the terminal 
response. 



5.9.4 CatOpenEnvelope 

CatEnvelopeTagType 
CatOpenEnvelope (BYTE * Length) ; 



Lengtii [out] Pointer that is updated with the length of the envelope 
RETURN The envelope tag 
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CatOpenEnvelope returns the envelope tag of the data buffer and the length of the envelope data. The data pointer is set 
to point to the envelope data. 

5.9.5 CatSendEnvelopeResponse 

void 

CatSendEnvelopeResponse (void) ; 

CatSendEnvelopeResponse sends the contents of the data buffer as a successful envelope response. 

5.9.6 CatSendEnvelopeErrorResponse 

void 

CatSendEnvelopeErrorResponse (void) ; 

This function sends the contents of the data buffer as an unsuccessful envelope response. 

5.9.7 CatPutData 

void 

CatPutData (BYTE Length, 

const void *Data) ; 



Length [in] Length of Data 

Data in Pointer to Data 



CatPutData appends Length bytes of data to the data buffer. 



5.9.8 CatPutByte 

void 

CatPutByte (BYTE Data) ; 



Data [in] Data byte. 



CatPutByte appends the supplied data byte to the data buffer. 



5.9.9 CatPutTLV 

void 

CatPutTLV (BYTE Tag, 

BYTE Length, 

const void * Value) ; 



Tag [in] Tag byte. 

Length [In] Length of value. 

Value [in] A pointer to the value. 



CatPutTLV appends a general TLV to the data buffer. 



5.9.10 CatPutBytePref ixedTLV 

void 

CatPutBytePrefixedTLV (BYTE Tag, 

BYTE Prefix, 
BYTE Length, 
const void * Value) ; 
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Tag 


[in] 


Tag byte. 


Prefix 


[in] 


Prefix byte. 


Length 


[in] 


Length of value. 


Value 


[in] 


A pointer to the value. 



CatPutBytePrefixedTLV appends a TLV to the data buffer with a single byte placed before the Value. 

5.9.11 CatPutOneByteTLV 

void 

CatPutOneByteTLV (BYTE Tag, 

BYTE Value); 



Tag [in] Tag byte. 
Value [in] Value byte. 



CatPutOneByteTLV appends a single byte valued TLV to the data buffer. 

5.9.12 CatPutTwoByteTLV 

void 

CatPutTwoByteTLV (BYTE Tag, 

BYTE Valuel, 

BYTE Value2) ; 



Tag [in] Tag byte. 

Valuel [in] First Value byte. 

Value2 [in] Second Value byte. 



CatPutTwoByteTLV appends a two byte valued TLV to the data buffer. 

5.9.13 CatGetByte 



BYTE 

CatGetByte (void) ; 



RETURN Data byte. 



CatGetByte returns the byte at the current data pointer and increments the data pointer by one. 



5.9.14 CatGetData 

const void * 

CatGetData (BYTE Length) ; 



Length [in] Length of Data 

RETURN Pointer to Data. 



CatGetData returns the current data pointer and increments the data pointer by Length bytes. 

5.9.15 CatFindNthTLV 

const void * 

CatFindNthTLV (BYTE Tag, 

BYTE Occurrence, 

BYTE *Length) ; 
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Tag 


[in] 


Tag to find. 


Occurrence 


[in] 


Occurrence of Tag to find with "1" being the first. 


Length: 


[out] 


Length of found TLV. 


RETURN 




Pointer to data of found TLV 



CatFindNthTLV finds the nth TLV that matches Tag in the data buffer, where nth is specified by the Occurrence 
parameter. If a match is found the data pointer is updated to the found TLV, the function returns a pointer to the found 
value and updates Length with the data length. If no match was found the function returns the nuU pointer and the data 
pointer is left unchanged. 

5.9.16 CatFindNthTLVInUserBuffer 

const void * 

CatFindNthTLVInUserBuffer (BYTE BufferLen, 

const void *Buffer, 

BYTE Tag, 

BYTE Occurrence, 

BYTE *Length) ; 



BufferLen 

Buffer 

Tag 

Occurrence 

Length 

RETURN 


[in] 
[in] 
[in] 
[In] 
[out] 


Length of buffer 
Buffer to search 
Tag to find. 

Occurrence of Tag to find with "1" being the first. 
Length of found TLV. 
Pointer to data of found TLV 



CatFindNthTLVInUserBuffer finds the nth TLV that matches Tag is the supplied buffer. The function returns a pointer 
to the found value and updates Length with the data length. If no match was found the function returns the null pointer. 

5.10 Network Services 
5.10.1 CatGetLocationlnformation 

CatGeneralResult 

CatGetLocationlnformation (CatLocationlnformation *LocationInformation) ; 



, ,. , . ^. r ,, A pointer to where the location information from the IVIE IS placed. Refer to 

Location nformation [out] ..0*1 n < i- .• ^ . . . ■, 

'■ ' the CatLocallnformation section for member details. 

o^T-, ,□., The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 

The GeneralResult code of the DISPLAY TEXT proactive command. 



CatProvideLocationlnformation requests the ME to send location information to the (U)SIM using the PROVIDE 
LOCAL INFORMATION proactive command. 

5.10.2 CatGetTiming Advance 

CatGeneralResult 

CatGetTimingAdvance (CatTimingAdvance * TimingAdvance) ; 



. J ^ A pointer to where the timing advance information from the ME is placed. 

iming vance [ou j Refer to the CatTimingAdvance section for member details. 

OCT-, ,0., The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatProvideTimingAdvance requests the ME to send timing advance information to the (U)SIM using the PROVIDE 
LOCAL INFORMATION proactive command. 
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5.10.3 CatGetlMEl 

CatGeneralResult 
CatGetlMEl (BYTE IMEIIB]) ; 



IMEI [out] A pointer to where the IMEI of the ME is placed. 

o^T-, ,□., The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetlMEl requests the ME to send the IMEI to the (U)SIM using the PROVIDE LOCAL INFORMATION proactive 
command. 

5.1 0.4 CatGetNetworkMeasurementResults 

CatGeneralResult 

CatGetNetworkMeasurementResults (BYTE MeasurementResultsllO]) ; 



MeasurementResults [out] A pointer to where the networl< measurement results from the ME is placed. 

RETURN '^^^ GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetNetworkMeasurementResults requests the ME to send the network measurement results to the (U)SIM using the 
PROVIDE LOCAL INFORMATION proactive command. 

5.10.5 CatGetDateTimeAndTimeZone 

CatGeneralResult 

CatGetDateTimeAndTimeZone (BYTE DateTlmeAndTlmeZonell]) ; 



DateTimeAndTimeZone [out] A pointer to where the date, time, and time zone from the ME is placed. 

o^T-, ,□., The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetDateTimeAndTimeZones requests the ME to send the date, time, and time zone information to the (U)SIM using 
the PROVIDE LOCAL INFORMATION proactive command. 

5.10.6 CatGetLanguage 

CatGeneralResult 

CatGetLanguage (BYTE Language [2] ) ; 



DateTimeAndTimeZone [out] A pointer to where the language from the ME is placed. 

o^T-, ,□., The GeneralResult code of the PROVIDE LOCAL INFORMATION proactive 

command. 



CatGetLanguage requests the ME to send the language information to the (U)SIM using the PROVIDE LOCAL 
INFORMATION proactive command. 



5.10.7 CatSetupCall 



CatGeneralResult 

CatSetupCall (BYTE CallSetupMessageLength, const void *CallSetupMessage, 
CatTypeOfNumberAndNumberingPlanldentifier TONandNPI, 

BYTE DiallingNumber Length, const void *DiallingNumber, 
CatSetupCallOptions Options, 

const Catlconldentifier *UserConfirmationIconIdentifier, 
BYTE CallSetupMessageLength, const void *CallSetupMessage, 
const Catlconldentifier *CallSeupIconIdentifier) ; 
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UserConfirmationMessageLength 
UserConfirmationMessage 

TONandNPI 

DiallingNumberLength 
DialingNumber 

Options 

UserConfirmationlconldentifier 

CallSetupMessageLength 
CallSetupMessage 

CallSetuplconldentifier 

RETURN 



[inj 
[in] 

[in] 

[in] 
[in] 

[In] 



[in] 

[in] 
[in] 

[in] 



Lengtii in bytes of UserConfirmationMessage. 

Message to display for user confirmation or NULL. 

Acceptable values for ttiis parameter are listed in 

CatTypeOfNumberAndNumberinqPlanldentifier . 

Lengtii In bytes of DiallingNumber. 

Number to call Is coded as binary-coded decimal. 

Acceptable values for ttiis parameter are listed In 

CatSetupCallOptions . 

Optional Icon identifier to use during the user confirmation pliase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier is NULL or if 

UserConfirmationlconldentifier.Uselcon is zero, no user confirmation 

pliase icon identifier is sent to tlie ME. 

Lengtii In bytes of CallSetupMessage. 

Message to display for call set up or NULL. 

Optional icon identifier to use during the call setup phase; see 

Catlconldentifier for member details. If CallSetuplconldentifier is 

NULL or if CallSetuplconldentifier.Uselcon is zero, no call setup phase 

icon identifier is sent to the ME. 

The GeneralResult code of the SET UP CALL proactive command. 



CatSetupCall and CatSetupCallEx issue the SET UP CALL proactive command to the ME. 

CatGeneralResult 

CatSetupCallEx (const CatSetupCallExParams *Params) ; 

The type CatSetupCallExParams is defined as follows: 

typedef struct 
{ 

// Mandatory fields 

CatSetupCallOptions Options; 

Cat TypeOfNumberAndNumberingP Ian Identifier TONandNPI; 

BYTE DiallingNumberLength; 

const void *DialingNumber; 

// Optional fields 

CatAlphaString UserConfirmationMessage; 

BYTE CapabilityConfigParamsLength; 

const void *CapabilityConf igParams; 

BYTE CalledPartySubaddressLength; 

const void *CalledPartySubaddress; 

Cat Time Interval RedialMaximumDuration; 

CatlconOption UserConf irmationlcon; 

CatAlphaString CallSetupMessage; 

CatlconOptions CallSetupIcon; 
} CatSetupCallExParams; 

With the following members: 
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Options 

TONandNPI 

DiailingNumberLength 
DiaiingNumber 

UserConfirmationMessage 

CapabilityConfigParamsLengthi 
Capability ConfigParams 
CaliedPartySubaddressLengtii 
CalledPartySubaddress 

RediaiMaximumDuration 

UserConfirmationlcon 

CaliSetupMessage 
CaliSetuplcon 



Acceptable values for this parameter are listed in CatSetupCallOptions . 
Acceptable values for this parameter are listed in 
CatTypeOfNumberAndNumberinqPlanldentifier . 
Length in bytes of DialiingNumber. 
Number to call is coded as binary-coded decimal. 
String to display during the user confirmation phase; see CatAlphaStrinq . 
If this parameter is null, no user confirmation message TLV is passed to 
the ME. 

Length in bytes of CapabilityConfigParams. 

A pointer to the capability configuration parameters as coded for EFccp. 
Length in bytes of CalledPartySubac/c/ress. 
The called party subaddress. 

An optional maximum duration for the redial mechanism. If the timelnterval 

member of this structure is zero, no duration TLV is sent to the ME. 

rA7e icon to display during the user confirmation phase. If the 

Uselcon member of this structure is zero, no user confirmation icon 

TLV is sent to the ME. 

String to display during the call set up phase; see CatAlphaStrinq . 

The icon to display during the call setup phase. 



Optional parameters are specifically chosen to use an all-zero binary representation. This means that it is simple to set 
up only the required members of the SetupCallExParams structure by zeroing the whole structure using memset, filling 
in the required members, and sending the result to CatSetupCallEx. As all optional parameters use a zero binary 
representation, the memset serves to initialise them all to the "not present" status. 



5.10.8 CatSendShortMessage 



CatGeneralResult 
CatSendShortMessage 



(BYTE TitleLength, const void *Title, 

CatTypeOfNumberAndNuniberingPlanldentifier TONandNPI, 
BYTE AddressLength, const void * Address, 
BYTE SmsTPDULength, const void *SmsTPDU, 
Cat SendShortMessageOpt ions Options, 
const Catlconldentifier * Iconldentifier) ; 



TitleLength 
Title 


[in] 
[in] 


TONandNPI 


[in] 


AddressLength 
Address 

SmsTPDULength 
SmTPDU 


[in] 
[in] 
[in] 
[in] 


Options 


[in] 


Iconldentifier 


[in] 


RETURN 





Length in bytes of Title. 

String to display while ME is sending a message. 

Acceptable values for this parameter are listed in 

CatTypeOfNumberAndNumberinqPlanldentifier . 

Length in bytes of Address. 

Address of the service center where message is being sent. 

Length in bytes of SmsTPDU. 

Formatted short message service (SMS) message to send. 

Specifies who packs the message. Acceptable values for this parameter are 

listed in CatSendShortMessaqeOptions . 

Optional icon identifier; see Catlconldentifier for member details. If 

Iconldentifier is NULL or if Iconldentifier. Uselcon is zero, no icon identifier is 

sent to the ME. 

The GeneralResult code of the SEND SHORT MESSAGE proactive 

command. 



CatSendShortMessage issues the SEND SHORT MESSAGE proactive command. 

5.10.9 CatSendSS 

CatGeneralResult 

CatSendSS (BYTE TitleLength, const void *Title, 

CatTypeOfNumberAndNuniberingPlanldentifier TONandNPI, 

BYTE SSStringLength, const void *SSString, 
const Catlconldentifier * Iconldentifier) ; 
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TitleLength 


[in] 


Length in bytes of Title. 


Title 


[in] 


String to display while IVIE is sending a message. 


TONandNPI 


[in] 


Acceptable values for this parameter are listed 


CatTvpeOfNumberAndNumberinqPlanldentifier. 


SSStringLength 


[in] 


Length in bytes of SSString. 


SSString 


[in] 


SS string to IVIE. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


RETURN 




The GeneralResult code of the SEND SS proactive command. 



CatSendSS issues the SEND SS proactive command to the ME. 

5.10.10 CatSendUSSD 

CatGeneralResult 

CatSendUSSD (BYTE TitleLength, const void *Title, 

CatDCSValue MessageDCS, BYTE MessageLength, const void *Message, 

CatDCSValue *MsgOutDCS, BYTE *MsgOutLength, void *MsgOut, 

const Catlconldentifier * Iconldentifier) ; 



TitleLength 


[in] 


The length in bytes of Title. 


Title 


[in] 


String to display while ME is sending a message. 


MessageDCS 


[in] 


The data-coding scheme for Message. Acceptable values for this parameter 
are listed in CatDCSValue. 


MessageLength 


[in] 


The length in bytes of Message. 


Message 


[in] 


Message to send. 


MsgOutDCS 


[out] 


Identifies type of DCS for the returned message. 


MsgOutLength 


[out] 


Length of the returned message in bytes. 


MsgOut 


[out] 


Returned string or message. 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon identifier is 
sent to the ME. 


RETURN 




The GeneralResult code of the SEND USSD proactive command. 



CatSendUSSD issues the SEND USSD proactive command. The terminal response is parsed and if successful the 
MsgOutDCS, MsgOutLength and MsgOut parameters are updated. 

5.1 0.1 1 CatOpenCSChannel 

CatGeneralResult 

CatOpenCSChannel (CatOpenChannelOptions Options, 

BYTE UserConfirmationLength, const void *UserConfirmation, 

const Catlconldentifier *UserConfimationIconIdentifier, 

CatTypeOfNumberAndNumberingPlanldentifier TONandNPI, 

BYTE DiallingNumberLength, const void *DiallingNumber, 

BYTE BearerDescription [3] , 

UINT16 *BufferSize, 

CatDevice *ChannelIdentifier) ; 
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Options [in] 

UserConfirmationLength [in] 

UserConfirmation [in] 



UserConfirmationlconldentifier [in] 



TONandNPI [in] 

DiallingNumberLength [in] 

DialingNumber [in] 

BearerDescription [in/out] 



BufferSize [in/out] 

Channelldentifier [out] 

RETURN 



Acceptable values for this parameter are listed in 

CatOpenChannelOptions . 

Length in bytes of UserConfirmation. 

String to display when IVIE alerts user that channel is to be opened. 

Optional icon identifier to use during the user confirmation phase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier is NULL or if 

UserConfirmationlconldentifier.Uselcon is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Acceptable values for this parameter are listed in 

CatTypeOfNumberAndNumberinqPlanldentifier . 

Length in bytes of DiallingNumber 

Number to call is coded as binary-coded decimal. 

Initially contains the bearer description parameters (data rate, bearer 

service and connection element) and is modified to the actual bearer 

description as allocated by the ME. 

Initially contains the desired buffer size and is modified to the actual 

buffer size as allocated by the ME. 

The channel identifier that has been allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatGeneralResult 

CatOpenCSChannelEx (const CatOpenCSChannelExParams *Params, 
CatDevice *ChannelIdentifier, 

BYTE BearerDescription [3] , 
UINT16 *BufferSize) ; 



Params 
Channei Identifier 

BearerDescription 

BufferSize 

RETURN 



[in] 
[out] 

[out] 

[out] 



Constant parameter set as defined below. 

The channel identifier that has been allocated by the ME. 

An array to which the actual bearer description allocated by the ME 

will be written. 

The actual buffer size allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatOpenCSChannel and CatOpenCSChannelEx issue the proactive command OPEN CHANNEL related to a CS 
bearer. The terminal response is parsed and if the command was successful the BearerDescription, BufferSize and 
Channelldentifier parameters are updated. 

The type CatOpenCSChannelExParams is defined as follows: 

typedef struct 
{ 

II Mandatory fields 

CatOpenChannelOptions Options; 

BYTE AddressLength; 

const BYTE *Address; 

BYTE BearerDescription [3] ; 

UINT16 BufferSize; 

// Optional fields 

CatAlphaString UserConf irmationMessage; 

Catlconldentifier UserConfirmationlconldentifier; 

BYTE SubAddressLength; 

const BYTE *SubAddress; 

BYTE DurationlDefined; 

CatTimelnterval Durationl; 

BYTE Duration2Defined; 

CatTimelnterval Duration2; 

CatAddressType LocalAddress; 

CatTextString UserLogin; 

CatTextString UserPassword; 

CAT_MEInterfaceTransportLevelType CAT_MEInterfaceTransport Level; 

CatAddressType DataDestinationAddress; 
} CatOpenCSChannelExParams; 

With the following members: 
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Options 

AddressLength 
Address 

BearerDeschption 

BufferSize 



UserConfirmationMessage 



UserConfirmationlcon Identifier 

SubAddressLengtIi 

SubAddress 

Duration 1 Defined 

Duration 1 

Duration2Defined 

Duration2 

LocalAddress 

UserLogin 

UserPassword 

CA T_l\/IEInterfaceTransportLevel 

DataDestinationAddress 



Acceptable values for this parameter are listed in 
CatOpenChannelOptions . This field is mandatory. 
Length in bytes of Address. This field is mandatory. 

The address to call. This field is mandatory. 
The desired bearer parameters (data rate, bearer service and 
connection element). This field is mandatory. 
The desired buffer size. This field is mandatory. 

String to display during the user confirmation phase; see CatAlphaStrinq . 
If this parameter is null, no user confirmation message TLV is passed to 
the ME. If UserConfirmationMessage is not null but 
UserConfirmationMessageLength is zero, a user confirmation message 
TLV is passed to the ME with the length component set to zero. 

The icon to display during the user confirmation phase. If the 
Uselcon member of this structure is zero, no user confirmation icon 
TLV is sent to the t^E. 
Length in bytes of SubAddress. 
The subaddress to call. 
Set to nonzero if Durationi is defined. 

Duration of reconnect tries; see CatTimelnterval . 

Set to nonzero if Duration2 is defined. 

Duration of timeout; see CatTimelnterval . 

The LocalAddress; see CatAddressType . 

The user login string. 

The user password string. 

See CAT MEInterfaceTransportLevelType . 

The DataDestinationAddress; see CatAddressType. 



5.10.12 CatOpenGPRSChannel 



CatGeneralResult 

CatOpenGPRSChannel (CatOpenChannelOptions Options, 

BYTE UserConflrmationLength, const void *UserConfirmation, 

const Catlconldentifier *UserConfirmationIconIdentifier, 

BYTE BearerDescription [8] , 

UINT16 *BufferSize, 

CatDevice *ChannelIdentifier) ; 



Options [in] 

UserConfirmationLengtIi [in] 

UserConfirmation [in] 



UserConfirmationlconldentifier [in] 



BearerDescription [in/out] 

BufferSize [in/out] 
Channelldentifier [out] 

RETURN 



Acceptable values for this parameter are listed in 

CatOpenChannelOptions . 

Length in bytes of UserConfirmation. 

String to display when ME alerts user that channel is to be opened. 

Optional icon identifier to use during the user confirmation phase; see 

Catlconldentifier for member details. If 

UserConfirmationlconldentifier \s NULL or if 

UserConfirmationlconldentifier.\Jse\cor\ is zero, no user confirmation 

phase icon identifier is sent to the ME. 

Initially contains the bearer description and is modified to the actual 

bearer description as allocated by the ME. 

Initially contains the desired buffer size and is modified to the actual 

buffer size as allocated by the ME. 

The channel identifier that has been allocated by the ME. 

The GeneralResult code of the OPEN CHANNEL proactive 

command. 



CatGeneralResult 

CatOpenGPRSChannelEx (const CatOpenGPRSChannelExParams *Params, 
CatDevice *ChannelIdentifier, 

BYTE ActualBearerDescription [8] , 
UINT16 *ActualBufferSize) ; 
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Params 


[in] 


Channelldentifier 


[out] 


ActualBearerDescription 


[out] 


ActualBufferSize 


[out] 


RETURN 





Constant parameter set as defined below. 

The channel identifier that has been allocated by the ME. 

An array to which the actual bearer description allocated by the ME 

will be written. 

The actual buffer size allocated by the ME. 

The General Result code of the OPEN CHANNEL proactive 

command. 



CatOpenGPRSChannel and CatOpenGPRSChannelEx issue the proactive command OPEN CHANNEL related to a 
GPRS bearer. The terminal response is parsed and if the command was successful the BearerDescription, BufferSize 
and Channelldentifier parameters are updated. 

The type CatOpenGPRSChannelExParams is defined as follows: 

typedef struct 
{ 

// Mandatory fields 

GsmOpenChannelOptions Options; 

BYTE AddressLength; 

const BYTE *Address; 

BYTE BearerDescription [8] ; 

UINT16 BufferSize; 

// Optional fields 

Cat AlphaSt ring UserConf irmationMessage; 

Catlconldentif ier UserConf irmat ion I con Identifier; 

BYTE AccessPointNameLength; 

const BYTE *AccessPointName; 

CatAddressType LocalAddress; 

CAT_ME_InterfaceTransportLevelType CAT_ME_InterfaceTransport Level; 

CatAddressType DataDestinationAddress; 
} GsmOpenGPRSChannelExParams; 

With the following members: 



Options 

AddressLength 
Address 

BearerDescription 
BufferSize 



UserConfirmationMessage 



UserConfirmationlconldentifier 

AccessPointNameLengtf) 

AccessPointName 

LocaiAddress 

CA T_l\/IE_lnterfaceTransportLevel 

DataDestinationAddress 



Acceptable values for this parameter are listed in 
CatOpenChannelOptions . This field is mandatory. 
Length in bytes of Address. This field is mandatory. 

The address to call. This field is mandatory. 
The desired bearer. This field is mandatory. 
The desired buffer size. This field is mandatory. 

String to display during the user confirmation phase; see CatAlphaStrinq . 
If this parameter is null, no user confirmation message TLV is passed to 
the ME. If UserConfirmationMessage is not null but 
UserConfirmationMessageLength is zero, a user confirmation message 
TLV is passed to the ME with the length component set to zero. 

The icon to display during the user confirmation phase. If the 

Uselcon member of this structure is zero, no user confirmation icon 

TLV is sent to the ME. 

The length in bytes of AccessPoint. 

The Access Point Name. 

See CatAddressType . 

See CAT MEInterfaceTransportLevelType . 

See CatAddressType. 
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5.10.13 CatCloseChannel 

CatGeneralResult 

CatCloseChannel (CatDevice Channelldentifier, 

BYTE TitleLength, const void *Title, 

const Catlconldentifier * Iconldentifier) ; 

Channelldentifier [in] The channel identifier as returned from one of the open commands 

TitleLength [in] The length in bytes of Title. 

Title [in] String to display while ME is closing the channel. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Iconldentifier \s NULL or if lconldentifier.\Jse\cor\ is zero, no icon identifier is 

sent to the ME. 
RETURN The GeneralResult code of the CLOSE CHANNEL proactive command. 

CatCloseChannel issues a CLOSE CHANNEL proactive command that closes an open channel. 

5.10.14 CatReceiveData 

CatGeneralResult 

CatReceiveData (CatDevice Channelldentifier, 

BYTE TitleLength, const void *Title, 

BYTE RequestedChannelDataLength, 

const Catlconldentifier * Iconldentifier, 

BYTE *ChannelData, 

BYTE *NumChannelBytesRead, 

BYTE *NumChannelBytesLeft) ; 



Channelldentifier [in] The channel identifier as returned from one of the open commands 

TitleLength [in] The length in bytes of Title. 

Title [in] String to display while ME is receiving data. 

RequestedChannelDataLength [in] The number of bytes requested to be read. 

Optional icon identifier; see Catlconldentifier for member details. If 
Iconldentifier [in] Icon Identifier \s NULL or if lconldentifier.Use\cor\ is zero, no icon 

identifier is sent to the ME. 
ChannelData [out] Received channel data. 

NumChannelBytesRead [out] The number of bytes received as channel data. 

The number of bytes remaining to be read from the channel buffer, or 

255 if there are more than 255 bytes left to be read. 
RETURN The GeneralResult code of the RECEIVE DATA proactive command. 



NumChannelBytesLeft [out] 



CatReceiveData issues a RECEIVE DATA proactive command that receives data from an open channel. The terminal 
response is parsed and if the command is successful the received data is copied into the ChannelData array and the 
NumChannelBytesRead and NumChannelBytesLeft parameters are updated. 

5.10.15 CatSendData 

CatGeneralResult 

CatSendData (CatDevice Channelldentifier, 
CatSendDataOptions Options, 

BYTE TitleLength, const void *Title, 

BYTE ChannelDataLength, 

const void *ChannelData, 

const Catlconldentifier * Iconldentifier , 

BYTE *ActualBytesSent) ; 



ETSI 



3GPP TS 31 .1 31 version 7.0.0 Release 7 40 ETSI TS 1 31 1 31 V7.0.0 (2007-06) 



Options [in] 



Channelldentifier [in] The channel identifier as returned from one of the open commands 

TitleLength [in] The length in bytes of Title. 

Title [in] String to display while ME is receiving data. 

Specifies who packs the message. Acceptable values for this 
parameter are listed in CatSendPataOptions . 

ChannelDataLength [in] The number of bytes to be sent from ChannelData. 

ChannelData [in] The data to be sent. 

Optional icon identifier; see Catlconldentifier for member details. If 

Icon Identifier [in] Icon Identifier \s NULL or if IconldentifierUselcon is zero, no icon 

identifier is sent to the ME. 

The number of bytes sent (derived from the CHANNEL DATA 
LENGTH TLV in the TERMINAL RESPONSE). 

RETURN The GeneralResult code of the SEND DATA proactive command. 



ActualBytesSent [out] 



CatSendData issues the proactive command SEND DATA that sends data to an open channeL 

5.10.16 CatGetChannelStatus 

CatGeneralResult 

CatGetChannelStatus (CatDevice Channelldentifier, void *ChannelStatus) ; 



Channelldentifier [in] The channel identifier. 

ChannelStatus [out] Returned channel status bytes. 

r.c-riiDM The GeneralResult code of the GET CHANNEL STATUS proactive 

command. 



CatGetChannelStatus issues a proactive command GET CHANNEL STATUS. The terminal response is parsed if the 
command is successful to find the status of the supplied channel. 

5.10.17 CatServiceSearch 

CatGeneralResult 

CatServiceSearch (CatBearer Bearerld, 

BYTE AttributeLength, void *Attributes, 

void *ServiceAvailability) ; 



Bearerld [in] The identifier of the bearer whose services will be searched. 

AttributeLengtti [in] The length of the following attribute array. 

Attrihijtp'i rinl Attributes that describe bearer services, typically in a bearer specific 

^ ' format. 



ServiceAvailability [in] 



List of services offered by the bearer that satisfy the attributes, 
typically in a bearer specific format. 



CatServiceSearch searches for a particular service on a bearer. 

5.10.18 CatGetService Information 

CatGeneralResult 

CatGetServicelnformation (BYTE TitleLength, const BYTE *Title, 

const catlconldentifier * Iconldentifier, 

CatBearer Bearerld, 

BYTE *AttributeLength, void *Attributes, 

void * Servicelnformation) ; 
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TitleLength 
Title 

Icon Identifier 

Bearerld 
AttributeLength 
Attributes 
Servicelnformation 



[in] The length in bytes of Title. 

[in] String to display acquiring service information. 

Optional icon identifier; see Catlconldentifier for member details, 
[in] Icon Identifier \s NULL or if IconldentifierUselcon is zero, no icon 

identifier is sent to the ME. 
[in] The identifier of the bearer whose service information is requested, 
[in] The number of bytes in the following attribute array. 

[in] Attributes describing the service information requested, 
[out] The requested information. 



CatGetServicelnformation retrieves information about a particular service on a bearer. 

5.10.19 CatDeclareService 

CatGeneralResult 

CatDeclareService (CatBearer Bearerld, BYTE Serviceld, 
CatTransportProtocol TransportProtocol , 

WORD *PortNumber, 

BYTE ServiceRecordLength, 

void *ServiceRecord) ; 



Bearerld 

TransportProtocol 

PortNumber 

ServiceRecordLength 

ServiceRecord 



[in] The identifier of the bearer for which this service is being offered. 

[in] The transport protocol on which the service is provided. 

[in] The port on which the service is provided. 

[in] The number of bytes in the following service record. 

[in] The service record describing the service. 



CatDeclareService describes a new service. 



5.10.20 CatRunATCommand 

CatGeneralResult 

CatRunATCommand (BYTE TitleLength, const void *Tltle, 

BYTE CommandLength, const void *Command, 
const Catlconldentifier * Iconldentlfler, 

void *Response, BYTE *ResponseLength) ; 



TitleLength 


[in] 


Length in bytes of Title. 


Title 


[In] 


String to display on ME while command is executing. 


CommandLength 


[in] 


Length in bytes of Command. 


Command 


[in] 


AT command string 

Optional icon identifier; see Catlconldentifier for member details. If 


Iconldentlfler 


[in] 


Iconldentlfler \s NULL or if IconldentifierUselcon is zero, no icon identifier is 
sent to the ME. 


Response 


[out] 


ME response string. 


ResponseLength 


[out] 


Length in bytes of ME response string. 


RETURN 




The GeneralResult code of the RUN AT COIVIMAND proactive 
command. 



CatRunATCommand issues the proactive command RUN AT COMMAND that sends an AT command to the ME. The 
terminal response is parsed and if successful the parameters Response and ResponseLength are updated. 

5.10.21 CatSendDTMFCommand 

CatGeneralResult 

CatSendDTMFCommand (BYTE TitleLength, const void *Tltle, 

BYTE DTMFCodeLength, const void *DTMFCode, 

const Catlconldentifier * Iconldentlfler) ; 
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TitleLength 


[in] 


Tlie lengtli in bytes of Title. 


Title 


[in] 


Title displayed while the DTMF string is sent to the networl<. 


DTMFCodeLength 


[in] 


The length in bytes of DTMFCode. 


DTMFCode 


[In] 


DTI\/IF string sent to the networl<. 

Optional icon identifier; see Catlconldentifier for member details. If 


Icon Identifier 


[in] 


Iconldentifier is NULL or if Iconldentifier.Uselcon is zero, no icon 
identifier is sent to the ME. 


RETURN 




The GeneralResult code of the SEND DTMF COMMAND proactive 

command. 



CatSendDTMF issues the proactive command SEND DTMF COMMAND that sends a dual tone multiple frequency 
(DTMF) string to the network. 

5.11 Supporting Data Types 

typedef unsigned char BYTE, 
typedef unsigned short WORD, 
typedef unsigned long int DWORD. 

5.11.1 CatRecordAccessMode 



typedef enum { 






NEXT 




= 0x02, 


PREVIOUS 




= 0x03, 


CURRENT 




= 0x04, 


ABSOLUTE 




= 0x04 


} CatRecordAccesE 


Mode; 





5.11.2 CatSearchMode 

typedef enum { 

BEGINNING_FORWARD, 

END_BACKWARD, 

NEXT_FORWARD, 

PRE V I OU S_BACKWARD 

} CatSearchMode; 

5.1 1 .3 CatFrameworkEventType 

typedef enum 
{ 

// Command monitoring events 

EVENT_TERMINAL_PROFILE_COMMAND, 

EVENT_STATUS_COMMAND 

EVENT_ENVELOPE_COMMAND, 

// Application lifecycle events start here 

EVENT_APPLICATION_LIFECYCLE_INSTALL = 0x20 

// Framework fabricated events start here 

EVENT_UPDATE_EF_SMS = 0x40 

EVENT_PROF I LE_DOWNLOAD , 

EVENT_FORMATTED_SMS_PP_UPD , 

E VENT_S TATU S_COMMAND , 

EVENT_UNFORMATTED_SMS_PP_UPD , 

EVENT_MENU_SELECTION, 

EVENT_FORMATTED_SMS_PP_ENV, 

EVENT_UNFORMATTED_SMS_PP_ENV, 

EVENT_FORMATTED_SMS_PP_CB, 

EVENT_MENU_SELECTION_HELP_REQUEST, 

EVENT_CALL_CONTROL_BY_S IM, 

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM, 

EVENT_TIMER_EXPIRATION, 

EVENT_DOWNLOAD_MT_CALL_EVENT, 

EVENT_DOWNLOAD_CALL_CONNECTED_EVENT, 

EVENT_DOWNLOAD_CALL_DISCONNECTED_EVENT, 

EVENT_DOWNLOAD_LOCATION_STATUS_EVENT, 
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EVENT_DOWNLOAD_USER_ACTIVITY_EVENT, 
EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE_EVENT, 
EVENT_DOWNLOAD_CARD_READER_STATUS_EVENT, 
EVENT_DOWNLOAD_LANGUAGE_SELECTION_EVENT, 
EVENT_DOWNLOAD_BROWSER_TERMINATION_EVENT, 
EVENT_DOWNLOAD_DATA_AVAILABLE_EVENT, 
EVENT_DOWNLOAD_CHANNEL_STATUS_EVENT, 
EVENT_UNRECOGNIZED_ENVELOPE, 
EVENT_TERMINAL_RESPONSE, 
EVENT_APPLICATION_INSTALL 
} CatFrameworkEventType; 

5. 11 .4 CatEnvelopeTagType 

typedef enum { 

SMS_PP_DOWNLOAD_TAG = OxDl, 

CELL_BROADCAST_TAG = 0xD2, 

MENU_SELECTION_TAG = 0xD3, 

CALL_CONTROL_TAG = 0xD4, 
MO_SHORT_MESSAGE_CONTROL_TAG = 0xD5, 

EVENT_DOWNLOAD_TAG = 0xD6, 

TIMER_EXPIRATION = 0xD7 

} CatEnvelopeTagType; 



5.11.5 CatEventType 



typedef enum { 




MT_CALL_EVENT 


= 0x00, 


CALL_CONNECTED_EVENT 


= 0x01, 


CALL_DISCONNECTED_EVENT 


= 0x02, 


LOCATION_STATUS_EVENT 


= 0x03, 


USER_ACTIVITY_EVENT 


= 0x04, 


IDLE_SCREEN_AVAILABLE 


= 0x05, 


CARD_READER_STATUS 


= 0x06, 


LANGUAGE_SELECTION 


= 0x07, 


BROWSER_TERMINATION 


= 0x08, 


DATA_AVAILABLE 


= 0x09, 


CHANNEL_STATUS 


= OxOA 


} CatEventType; 





5.11.6 CatTextString 

typedef struct 
{ 

CatDCSValue DCSValue; 

BYTE TextStringLength; 

const void *TextString; 
} CatTextString; 

5.11.7 CatAlphaString 

typedef struct 
{ 

BYTE AlphaStringLength; 

const void *AlphaString; 
} CatTextString; 

5.11.8 Catlcon Identifier 

typedef struct 
{ 

BYTE Uselcon; 

BYTE Iconldentifier; 

BYTE IconOptions; 
} Catlconldentif ier; 

The Catlconldentif ier structure is defined as follows: 
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Uselcon 
Icon Identifier 

IconOptions 



If zero, the icon identifier is not used in tine proactive command. If non- 
zero, the Iconldentifier and IconOption members are used in the 
proactive command. 
Index of the icon to display. 

Options with which to display the icon selected from CaticonOption . 
This is specified as a BYTE rather than CatlconOptios as, in C, an 
enumeration uses the same storage as an int which is at least 1 6 bits, 
whereas the proactive commands that use these identifiers use 8-bit 
quantities. 



5.11.9 CaticonOption 



typedef enum 




SHOW_WITHOUT_TEXT = 
SHOW WITH TEXT 


= 0x00 
= 0x01 



} CaticonOption; 



5.11.10 CatDCSValue 

typedef enum 

{ 

DCS_SMS_PACKED = 0x00, 
DCS_SMS_UNPACKED = 0x04, 
DCS_SMS_UNICODE = 0x08 

} CatDCSValue; 



5.11.11 CatDisplayTextOptions 



typedef enum 



NORMAL_PRIORITY_AUTO_CLEAR 
NORMAL_PRIORITY_USER_CLEAR 
HIGH_PRIORITY_AUTO_CLEAR 
HIGH_PRIORITY_USER_CLEAR 
} CatDisplayTextOptions; 



0x00, 
0x80, 
0x01, 
0x81 



5.11.12 CatGetlnKeyOptions 



typedef enum 

{ 

YES_NO_OPTION_NO_HELP 

YES_NO_OPTION_WITH_HELP 

DIGITS_ONLY_NO_HELP 

DIGITS_ONLY_WITH_HELP 

SMS_C HARAC TER_NO_HE LP 

SMS_CHARACTER_WITH_HELP 

UCS2_CHARACTER_N0_HELP 

UCS2_CHARACTER_WITH_HELP 

} CatGetlnKeyOptions; 






x04, 





x84, 





xOO, 





x80. 





xOl, 





x81, 





x03. 





x83 



5.11.13 CatGetlnputOptions 

typedef enum 

{ 

PACKED_DIGITS_ONLY_NO_HELP = 0x08, 

PACKED_DIGITS_ONLY_WITH_HELP = 0x88, 

PACKED_DIGITS_ONLY_NO_ECHO_NO_HELP = OxOC, 

PACKED_DIGITS_ONLY_NO_ECHO_WITH_HELP = 0x8C, 

UNPACKED_DIGITS_ONLY_NO_HELP = 0x00, 

UNPACKED_DIGITS_ONLY_WITH_HELP = 0x80, 

UNPACKED_DIGITS_ONLY_NO_ECHO_NO_HELP = 0x04, 

UNPACKED_DIGITS_ONLY_NO_ECHO_WITH_HELP = 0x84, 

PACKED_SMS_ALPHABET_NO_HELP = 0x09, 

PACKED_SMS_ALPHABET_WITH_HELP = 0x89, 

PACKED_SMS_ALPHABET_NO_ECHO_NO_HELP = OxOD, 

PACKED_SMS_ALPHABET_NO_ECHO_HELP = 0x8D, 

UNPACKED SMS ALPHABET NO HELP = 0x01, 
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UNPACKED_SMS_ALPHABET_WITH_HELP = 0x81, 

UNPACKED_SMS_ALPHABET_NO_ECHO_NO_HELP = 0x05, 

UNPACKED_SMS_ALPHABET_NO_ECHO_WITH_HELP = 0x85, 

UCS2_ALPHABET_N0_HELP = 0x03, 

UCS2_ALPHABET_WITH_HELP = 0x83, 

UCS2_ALPHABET_N0_ECH0_N0_HELP = 0x07, 

UCS2_ALPHABET_N0_ECH0_WITH_HELP = 0x87 
Cat Get Input Opt ions; 



5.11.14 CatSelectltemOptions 



typedef enum 



PRESENT_AS_DATA_VALUES_NO_HELP 
PRESENT_AS_DATA_VALUES_WITH_HELP 
PRESENT_AS_NAVIGATION_OPTIONS_NO_HELP 
PRESENT_AS_NAVIGATION_OPTIONS_WITH_HELP 
DEFAULT_STYLE_NO_HELP 
DEFAULT_STYLE_WITH_HELP 
} CatSelectltemOptions; 



0x01, 
0x81, 
0x03, 
0x83, 
0x00, 
0x80 



5.11.15 CatTimeUnit 

typedef enum 

{ 

GSM_MINUTES = 0x00, 

GSM_SECONDS = 0x01, 

GSM_TENTHS_OF_SECONDS = 0x02 

} CatTimeUnit; 



5.11.16 CatTone 



typedef enum 



DIAL_TONE 

CALLER_BUSY 

CONGESTION 

RAD 1 0_P ATH_ACKNOWLED GE 

CALL_DROPPED 

SPECIAL_INFORMATION_OR_ERROR 

CALL_WAITING_TONE 

RINGING_TONE 

GENERAL_BEEP 

POSITIVE_ACKNOWLEDGE_TONE 

NEGATIVE_ACKNOWLEDGE_TONE 

CatTone; 



0x01, 
0x02, 
0x03, 
0x04, 
0x05, 
0x06, 
0x07, 
0x08, 
0x10, 
0x11, 
0x12 



5.11.17 CatRef reshOptions 

typedef enum 

{ 

REFRESH_SIM_INIT_AND_FULL_FILE_CHANGE_NOTIFICATION = 0x00, 
REFRESH_FILE_CHANGE_NOTIFICATION = 0x01, 

REFRESH_SIM_INIT_AND_FILE_CHANGE_NOTIFICATION = 0x02, 
REFRESH_SIM_INIT = 0x03, 

REFRESH_SIM_RESET = 0x04 

} CatRef reshOptions; 



5.11.18 CatGetReaderStatusOptions 

typedef enum 
{ 

CARD_READER_STATUS = 0x00, 

CARD_READER_IDENTIFIER = 0x01 
} CatGetReaderStatusOptions; 
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5.11.19 CatDevice 



typedef enum 



DEVICE. 


_KEPYAD 




= 


0x01 


DEVICE. 


.DISPLAY 




= 


0x02 


DEVICE. 


.EARPIECE 




= 


0x03 


DEVICE. 


_CARD_READER_ 


.0 


= 


0x10 


DEVICE. 


_CARD_READER_ 


.1 


= 


0x11 


DEVICE. 


_CARD_READER_ 


.2 


= 


0x12 


DEVICE. 


_CARD_READER_ 


.3 


= 


0x13 


DEVICE. 


_CARD_READER_ 


.4 


= 


0x14 


DEVICE. 


_CARD_READER_ 


.5 


= 


0x15 


DEVICE. 


_CARD_READER_ 


.6 


= 


0x16 


DEVICE. 


_CARD_READER_ 


.7 


= 


0x17 


DEVICE. 


_CHANNEL_1 




= 


0x21 


DEVICE. 


_CHANNEL_2 




= 


0x22 


DEVICE. 


_CHANNEL_3 




= 


0x23 


DEVICE. 


_CHANNEL_4 




= 


0x24 


DEVICE. 


_CHANNEL_5 




= 


0x25 


DEVICE. 


_CHANNEL_6 




= 


0x26 


DEVICE. 


_CHANNEL_7 




= 


0x27 


DEVICE. 


_SIM 




= 


0x81 


DEVICE. 


_ME 




= 


0x82 


DEVICE. 


.NETWORK 




= 


0x83 


CatDevice; 









5.11.20 CatGeneralResult 



typedef enum 

{ 

CAT_COMMAND_SUCCESSFUL = 0x00, 

CAT_COMMAND_SUCCESSFUL_WITH_PARTIAL_COMPREHENSION = 0x01, 

CAT_COMMAND_SUCCESSFUL_WITH_MISSING_INFORMATION = 0x02, 

CAT_REFRESH_SUCCESSFUL_WITH_ADDITIONAL_EFS_READ = 0x03, 

CAT_COMMAND_SUCCESSFUL_BUT_ICON_NOT_FOUND = 0x04, 

CAT_COMMAND_SUCCESSFUL_BUT_MODIFIED_BY_CALL_CONTROL = 0x05, 

CAT_COMMAND_SUCCESSFUL_BUT_LIMITED_SERVICE = 0x06, 

CAT_COMMAND_SUCCESSFUL_WITH_MODIFICATION = 0x07, 

CAT_ABORTED_BY_USER = 0x10, 

CAT_BACKWARD = 0x11, 

CAT_NO_RESPONSE = 0x12, 

CAT_HELP_REQUIRED = 0x13, 

CAT_USSD_ABORTED_BY_USER = 0x14, 

CAT_ME_UNABLE_TO_PROCESS_COMMAND = 0x20, 

CAT_NETWORK_UNABLE_TO_PROCESS_COMMAND = 0x21, 

CAT_USER_REJECTED_SETUP_CALL = 0x22, 

CAT_USER_CLEARED_BEFORE_RELEASE = 0x23, 

CAT_ACTION_CONTRADICT_TIMER_STATE = 0x24, 

CAT_TEMP_PROBLEM_IN_CALL_CONTROL = 0x25, 

CAT_LAUNCH_BROWSER_ERROR = 0x26, 

CAT_COIXMAND_BEYOND_ME_CAPABILITIES = 0x30, 

CAT_COMMAND_TYPE_NOT_UNDERSTOOD = 0x31, 

CAT_COMMAND_DATA_NOT_UNDERSTOOD = 0x32, 

CAT_COMMAND_NUMBER_NOT_KNOWN = 0x33, 

CAT_SS_RETURN_ERROR = 0x34, 

CAT_SMS_RP_ERROR = 0x35, 

CAT_REQUIRED_VALUES_MISSING = 0x36, 

CAT_USSD_RETURN_ERROR = 0x37, 

CAT_MULTIPLE_CARD_COMiyiAND_ERROR = 0x3 8, 

CAT_PERMANENT_PROBLEM_IN_SMS_OR_CALL_CONTROL = 0x39, 

CAT_BEARER_INDEPENDENT_PROTOCOL_ERROR = 0x3A 

} CatGeneralResult; 
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5.11.21 CatTimerValue 

typedef struct 
{ 

BYTE hour; 

BYTE minute; 

BYTE second; 
} CatTimerValue; 

The CatTimerValue data type has three one-byte values: 



tiour 

Minute 

Second 


Hours part of timer. 
Minutes part of timer. 
Seconds part of timer. 



5.11.22 CatTi me Interval 

typedef struct 
{ 

BYTE timeUnit; 

BYTE timelnterval; 
} CatTimelnterval; 

The CatTimlnterval data type has two one-byte values: 



One of the CatTimeUnit enumeration values. This is specified as a BYTE rather than CatTlmeUnit 
timeUnit as, in C, an enumeration uses the same storage as an int which is at least 16 bits, whereas the 

proactive commands that use these identifiers use 8-bit quantities. 
Timelntervai The number of timeUnits. 



5.11.23 CatFileStatus 



typedef struct 



WORD recordLength; 
WORD numberOf Records; 
BYTE lengthOfTrailer; 
BYTE trailer [] ; 
} CatEFStatus; 

typedef struct 
{ 



BYTE numberOf DFs; 
BYTE numberofEFs; 

BYTE CHVlStatus; 

BYTE unblockCHVlStatus; 

BYTE CHV2Status; 

BYTE unblockCHV2Status; 

BYTE lengthOfTrailer; 
BYTE trailer [] ; 
} CatDFStatus; 

typedef struct 
{ 
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DWORD totalFileSize; 
UINT16 filelD; 

BYTE fileDescriptorByte; 

BYTE fileType; // 00=RFU, 01=MF, 02=DF, 04=EF 

BYTE fileLifeCycleStatus; 

union 

{ 

CatEFStatus ef; 

CatDFStatus df; 
} u; 
} CatFileStatus; 

5.1 1 .24 CatLanguageNotificationOptions 

typedef enum 
{ 

LANGUAGE_NON_SPECIFIC_NOTIFICATION = 0x00, 

LANGUAGE_SPECIFIC_NOTIFICATION = 0x01 
} CatLanguageNotificationOptions; 

5.1 1 .25 CatLocationlnformation 

typedef struct 
{ 

BYTE mobileCountryNetworkCodes [3] ; 

BYTE LAC [2] ; 

BYTE cellID[2]; 
} CatLocationlnformation; 

5.1 1 .26 CatTiming Advance 

typedef struct 
{ 

BYTE MEStatus; 

BYTE timingAdvance; 
} CatTimingAdvance; 

5.1 1 .27 CatLaunchBrowserOptions 

typedef enum 

{ 

LAUNCH_BROWSER_IF_NOT_ALREADY_LAUNCHED = 0x00, 

USE_EXISTING_BROWSER = 0x02, 

CLOSE_EXISTING_BROWSER_AND_LAUNCH_NEW_BROWSER = 0x03 

} CatLaunchBrowserOptions; 

5.1 1 .28 CatSetupCallOptions 

typedef enum 

{ 

CALL_ONLY_IF_NOT_BUSY = 0x00, 

CALL_ONLY_IF_NOT_BUSY_WITH_REDIAL = 0x01, 

CALL_AND_PUT_ALL_OTHER_CALLS_ON_HOLD = 0x02, 

CALL_AND_PUT_ALL_OTHER_CALLS_ON_HOLD_WITH_REDIAL = 0x03, 

CALL_AND_DISCONNECT_ALL_OTHER_CALLS = 0x04, 

CALL_AND_DISCONNECT_ALL_OTHER_CALLS_WITH_REDIAL = 0x05 

} CatSetupCallOptions; 
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5.1 1 .29 CatTypeOfNumberAndNumberingPlanldentifier 

typedef enum 



TON_UNKNOWN_AND_NP I_UNKNOWN = 0x80, 

TON_INTERNATIONAL_AND_NPI_UNKNOWN = 0x90, 

TON_NATIONAL_AND_NPI_UNKNOWN = OxAO, 

TON_NETWORK_AND_NPI_UNKNOWN = OxBO, 

TON_SUBSCRIBER_AND_NPI_UNKNOWN = OxCO, 

TON_UNKNOWN_AND_NPI_TELEPHONE = 0x81, 

TON_INTERNATIONAL_AND_NPI_TELEPHONE = 0x91, 

TON_NATIONAL_AND_NPI_TELEPHONE = OxAl, 

TON_NETWORK_AND_NPI_TELEPHONE = OxBl, 

TON_SUBSCRIBER_AND_NPI_TELEPHONE = OxCl, 



TON_UNKNOWN_AND_NP I_DATA 
TON_INTERNATIONAL_AND_NP I_DATA 
TON_NATIONAL_AND_NPI_DATA 
TON_NETWORK_AND_NP I_DATA 
TON_SUBSCRIBER_AND_NPI_DATA 



0x83, 
0x93, 
0xA3, 
0xB3, 
0xC3, 



TON_UNKNOWN_AND_NP I_TELEX 
TON_INTERNATIONAL_AND_NPI_TELEX 
TON_NAT I ONAL_AND_NP I_TE LEX 
TON_NE TWORK_AND_NP I_TE LEX 
TON_SUBSCRIBER_AND_NPI_TELEX 



0x84, 
0x94, 
0xA4, 
0xB4, 
0xC4, 



TON_UNKNOWN_AND_NPI_NATIONAL = 0x88, 

TON_INTERNATIONAL_AND_NPI_NATIONAL = 0x98, 

TON_NATIONAL_AND_NPI_NATIONAL = 0xA8, 

TON_NETWORK_AND_NPI_NATIONAL = 0xB8, 

TON_SUBSCRIBER_AND_NPI_NATIONAL = 0xC8, 

TON_UNKNOWN_AND_NPI_PRIVATE = 0x89, 

TON_INTERNATIONAL_AND_NPI_PRIVATE = 0x99, 

TON_NATIONAL_AND_NPI_PRIVATE = 0xA9, 

TON_NETWORK_AND_NPI_PRIVATE = 0xB9, 

TON_SUBSCRIBER_AND_NPI_PRIVATE = 0xC9, 



TON_UNKNOWN_AND_NP I_ERMES 
TON_INTERNATIONAL_AND_NPI_ERMES 
TON_NAT I ONAL_AND_NP I_ERME S 
TON_NETWORK_AND_NPI_ERMES 
TON_SUBSCRIBER_AND_NPI_ERMES 



0x8A, 
0x9A, 
OxAA, 
OxBA, 
OxCA 



} Cat TypeOfNumberAndNumberingP Ian Identifier; 



5.1 1 .30 CatSendShortMessageOptions 

typedef enum 
{ 

PACKING_NOT_REQUIRED = 0x00, 

PACKING_BY_THE_ME_REQUIRED = 0x01 
} CatSendShortMessageOptions; 

5.1 1 .31 CatSendDataOptions 

typedef enum 
{ 

STORE_DATA_IN_TX_BUFFER = 0x00, 

SEND_DATA_IMMEDIATELY = 0x01 
} CatSendDataOptions; 
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5.1 1 .32 CatMEInterfaceTransportLevelType 

typedef struct 



enum 
{ 

UDP = 0x01, 

TCP = 0x02 
} TransportProtocolType; 
UINT16 CAT_ME_PortNumber; 
CAT_MEInterfaceTransportLevelType; 



5.11.33 CatBearer 



typedef enum 




i 

BEARER_SMS = 


= 0x00, 


BEARER_CSD = 


= 0x01, 


BEARER_USSD = 


= 0x02, 


BEARER_GPRS = 


= 0x03 


} CatBearer; 





5.1 1 .34 CatOpenChannelOptions 

typedef enum 

{ 

0N_DEMAND_LINK_ESTABL1SHMENT = 0x00, 
IMMEDIATE_LINK_ESTABLISHMENT = 0x01 

} CatOpenChannelOptions; 



5.11.35 CatAddressType 



typedef struct 
{ 

enum 

{ 

IPV4 = 0x21, 
IPV6 = 0x97 

} AddressType; 

BYTE AddressLength; 

const void *Address; 
} CatAddressType; 



5.11.36 CatFID 



#define FID_DF_GRAPHICS 0x5F50 
#define FID_DF_TELECOM 0x7F10 



#def ine 


FID_ 


_EF_ 


_ADN 


0x6F3A 


#def ine 


FID_ 


_EF_ 


_ARR 


0x2F06 


#def ine 


FID_ 


_EF_ 


_BDN 


0x6F4D 


#def ine 


FID_ 


_EF_ 


_CCP 


0x6F3D 


#define 


FID_ 


_EF_ 


_DIR 


0x2F00 


#define 


FID_ 


_EF_ 


_EXT1 


0x6F4A 


#define 


FID_ 


_EF_ 


_EXT2 


0x6F4B 


#def ine 


FID_ 


_EF_ 


_EXT3 


0x6F4C 


#def ine 


FID_ 


_EF_ 


_EXT4 


0x6F4E 


#def ine 


FID_ 


_EF_ 


_FDN 


0x6F3B 


#def ine 


FID_ 


_EF_ 


_ICCID 


0x2FE2 


#def ine 


FID_ 


_EF_ 


_IMG 


0x4F20 


#def ine 


FID_ 


_EF_ 


_LND 


0x6F44 


#def ine 


FID_ 


_EF_ 


_MSISDN 0x6F40 


#def ine 


FID_ 


_EF_ 


_PL 


0x2F05 


#define 


FID_ 


_EF_ 


_SDN 


0x6F49 


#def ine 


FID_ 


_EF_ 


_SMS 


0x6F3C 


#def ine 


FID_ 


_EF_ 


_SMSP 


0x6F42 


#def ine 


FID_ 


_EF_ 


_SMSR 


0x6F47 


#def ine 


FID_ 


_EF_ 


_SMSS 


0x6F43 
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5.11.37 CatTextFormat 



#define TEXT_FORMAT_LEFT 

#define TEXT_FORMAT_CENTER 

#define TEXT_FORMAT_RIGHT 

#define TEXT_FORMAT_LANGUAGE_DEPENDENT 

#define TEXT_FORMAT_NORMAL_SIZE 

#define TEXT_FORMAT_LARGE_SIZE 

#define TEXT_FORMAT_SMALL_SIZE 

#define TEXT_FORMAT_BOLD 

#define TEXT_FORMAT_ITALIC 

#define TEXT_FORMAT_UNDERLINED 

#define TEXT_FORMAT_STRIKETHROUGH 



0x00 
0x01 
0x02 
0x03 
0x00 
0x04 
0x08 
0x10 
0x20 
0x40 
0x80 



5.1 1 .38 CatTextForegroundColour 



typedef enum { 






BLACK 


= 


0x00 


DARK_GREY 


= 


0x01 


DARK_RED 


= 


0x02 


DARK_YELLOW 


= 


0x03 


DARK_GREEN 


= 


0x04 


DARK_CYAN 


= 


0x05 


DARK_BLUE 


= 


0x06 


DARK_MAGENTA 


= 


0x07 


GREY 


= 


0x08 


WHITE 


= 


0x09 


BRIGHT_RED 


= 


OxOA 


BRIGHT_YELLOW 


= 


OxOB 


BRIGHT_GREEN 


= 


OxOC 


BRIGHT_CYAN 


= 


OxOD 


BRIGHT_BLUE 


= 


OxOE 


BRIGHT_MAGENTA 


= 


OxOF 


} CatTextForegroundColour; 







5.1 1 .39 CatTextBackgroundColour 



typedef enum ( 








BLACK 




= 


0x00 


DARK_GREY 




= 


0x10 


DARK_RED 




= 


0x20 


DARK_YELLOW 




= 


0x30 


DARK_GREEN 




= 


0x40 


DARK_CYAN 




= 


0x50 


DARK_BLUE 




= 


0x60 


DARK_MAGENTA 




= 


0x70 


GREY 




= 


0x80 


WHITE 




= 


0x90 


BRIGHT_RED 




= 


OxAO 


BRIGHT_YELLOW 




= 


OxBO 


BRIGHT_GREEN 




= 


OxCO 


BRIGHT_CYAN 




= 


OxDO 


BRIGHT_BLUE 




= 


OxEO 


BRIGHT_MAGENTA 




= 


OxFO 


} CatTextBackgroun 


dColour; 
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Annex A (normative): 

Application executable architecture 



Name 


Value 


Meaning 


EM NONE 





No machine 


EM M32 


1 


AT&T WE 32100 


EM SPARC 


2 


SPARC 


EM 386 


3 


Intel 80386 


EM 68K 


4 


Motorola 68000 


EM 88K 


5 


Motorola 88000 


RESERVED 


6 


Reserved for future use 


EM 860 


7 


Intel 80860 


EM MIPS 


8 


MIPS 1 Architecture 


EM S370 


9 


IBM System/370 Processor 


EM MIPS RS3 LE 


10 


MIPS RS3000 Little-endian 


RESERVED 


11-14 


Reserved for future use 


EM PARISC 


15 


Hewlett-Packard PA-RISC 


RESERVED 


16 


Reserved for future use 


EM VPP500 


17 


Fujitsu VPP500 


EM SPARC32PLUS 


18 


Enhanced instruction set SPARC 


EM 960 


19 


Intel 80960 


EM PPC 


20 


PowerPC 


EM PPC64 


21 


64-bit PowerPC 


RESERVED 


22-35 


Reserved for future use 


EM V800 


36 


NEC V800 


EM FR20 


37 


Fujitsu FR20 


EM RH32 


38 


TRW RH-32 


EM RCE 


39 


Motorola RCE 


EM ARM 


40 


Advanced RISC Machines ARM 


EM ALPHA 


41 


Digital Alpha 


EM SH 


42 


Hitachi SH 


EM SPARCV9 


43 


SPARC Version 9 


EM TRICORE 


44 


Infineon Tricore embedded processor 


EM ARC 


45 


Argonaut RISC Core 


EM H8 300 


46 


Hitachi H8/300 


EM H8 300H 


47 


Hitachi H8/300H 


EM H8S 


48 


Hitachi H8S 


EM H8 500 


49 


Hitachi H8/500 


EM lA 64 


50 


Intel IA-64 processor architecture 


EM MIPS X 


51 


Stanford MIPS-X 


EM COLDFIRE 


52 


Motorola ColdFire 


EM 68HC12 


53 


Motorola M68HC1 2 


EM MMA 


54 


Fujitsu MMA Multimedia Accelerator 


EM PCP 


55 


Siemens PCP 


EM NCPU 


56 


Sony nCPU embedded RISC processor 


EM NDR1 


57 


Dense NDR1 microprocessor 


EM STARCORE 


58 


Motorola Star*Core processor 


EM ME16 


59 


Toyota ME16 processor 


EM ST100 


60 


STMicroelectronics ST100 processor 


EM TINYJ 


61 


Advanced Logic Corp. TinyJ embedded processor family 


Reserved 


62-65 


Reserved for future use 


EM FX66 


66 


Infineon FX66 microcontroller 


EM ST9PLUS 


67 


STMicroelectronics ST9+ 8/16 bit microcontroller 


EM ST7 


68 


STMicroelectronics ST7 8-bit microcontroller 


EM 68HC16 


69 


Motorola MC68HC16 Microcontroller 


EM 68HC11 


70 


Motorola MC68HC1 1 Microcontroller 


EM 68HC08 


71 


Motorola MC68HC08 Microcontroller 


EM 68HC05 


72 


Motorola MC68HC05 Microcontroller 


EM SVX 


73 


Silicon Graphics SVx 


EM ST19 


74 


STMicroelectronics ST19 8-bit microcontroller 


EM VAX 


75 


Digital VAX 


EM CRIS 


76 


Axis Communications 32-bit embedded processor 
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Name 


Value 


Meaning 


EM JAVELIN 


77 


Infineon Technologies 32-bit embedded processor 


EM FIREPATH 


78 


Element 14 64-bit DSP Processor 


EM ZSP 


79 


LSI Logic 16-bit DSP Processor 


EM MMIX 


80 


Donald Knuth's educational 64-bit processor 


EM HUANY 


81 


Harvard University machine-independent object files 


EM PRISM 


82 


SiTera Prism 


EM MEL 


83 


Multos Executable Language (MEL) byte codes 


EM RTE 


84 


Microsoft Smart Card for Windows Runtime Environment byte codes 



£75/ 



3GPP TS 31.131 version 7.0.0 Release 7 54 ETSI TS 131 131 V7.0.0 (2007-06) 



Annex B (informative): 

Example 

/** 

** Example of Toolkit Application written for the C SIM API 
*/ 

#pragma AID A0000000090001 

#include <stdlib.h> 
tinclude "application. h" 
#include "cat.h" 
#include "catlow.h" 

tdefine DF_GSM 0x7F20 
#define EF_PUCT 0x6F41 

const BYTE SERVER_OPERATION = OxOF; 

const BYTE EXIT_REQUESTED_BY_USER = 0x10; 

static const char menuEntry [ ] = "Servicel"; 

static const char menuTitle [ ] = "MyMenu"; 

static char iteml[] = "ITEMl" 

static char item2[] = "ITEM2" 

static char item3[] = "ITEM3" 

static char item4[] = "ITEM4" 

static char textDText[] = "Hello, world"; 

static char textGInput[] = "Your name?"; 

BYTE Itemldentifier; 

static BYTE * byteptr; 

static void * bufptr; 

static BYTE buffer [10]; 

static BYTE itemid; 

static BYTE result; 

static BYTE repeat; 

void main (void) 
{ 

switch (CatGetFrameworkEvent ( ) ) 
{ 

case EVENT_APPLICATION_LIFECYCLE_INSTALL: 
// Define the application Menu Entry and register to the EVENT_MENU_SELECTION 
CatSetMenuString ( 1, sizeof (menuEntry ), (const void *) MenuEntry, NULL, 0, ) ; 
// register to the EVENT_UNFORMATTED_SMS_PP_ENV 
CatNotifyOnEnvelope (SMS_PP_DOWNLOAD_TAG, 1) ; 
break; 
case EVENT_ENVELOPE_COMMAND : 
{ 

BYTE length; 

switch (CatOpenEnvelope (&length) ) 
{ 
case MENU_SELECTION_TAG: 

// Prepare the Select Item proactive command 
// Append the Menu Title 
CatSelectltem (sizeof (MenuTitle) , 
(const void *)MenuTitle, 
DEFAULT_STYLE_NO_HELP) ; 

// add all the Item 

CatSelectAddItem(sizeof (iteml) , (const void *)iteml,l) 
CatSelectAddItem(sizeof (item2) , (const void *)item2,2) 
CatSelectAddItem(sizeof (item3) , (const void *)item3,3) 
CatSelectAddltem (sizeof (item4) , (const void *)item4,4) 
// ask the CAT Toolkit Framework to send 
//the proactive command and check the result 

if ( !CatEndSelectItem(& Itemid, NULL) ) 
{ 

switch (Itemid) 

{ 

case 1: 



case 2 
case 3 



// DisplayText 



CatDisplayText (DCS_SMS_UNPACKED, 



(const void *) textDText, 



sizeof (textDText) , 
NORMAL_PRIORITY_USER_CLEAR, NULL, 0); 
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break; 
case 4: // Ask the user to enter data and display it 
repeat=0; 
do 
{ 

if (CatGetlnput (DCS_SMS_UNPACKED, 
sizeof (textGInput) , 
(const void *) textGInput, 
UNPACKED_SMS_ALPHABET_NO_HELP, 
DCS_SMS_UNPACKED, 0, NULL, 
0, sizeof (buffer) , NULL, 
(CatDCSValue *)&result, 
Srepeat, 

(void *) buffer) ==EXIT_REQUESTED_BY_USER) 
break; 
// display the entered text 
CatDisplayText ((CatDCSValue ) result, 
repeat, (const void *) buffer, 
NORMAL_PRIORITY_USER_CLEAR, NULL, 0); 
} while (repeat); 
) 
} 
break; 
case EVENT_UNFORMATTED_SMS_PP_ENV: 
CatOpenEnvelope (Sresult) ; 

byteptr= (BYTE * ) catGetData ( 1 ) ; /* go to numberlength */ 
result= (*byteptr) >>1; 
/* calculate numberlength, rounded up */ 
if ( (*byteptr) &1) result++; 
catGetData (result+12 ) ; /* move to the beginning of the data */ 
// get the offset of the instruction in the TP-UD field 
CatGetData (SERVER_OPERATION) ; 
result=CatGetBYTE ( ) ; 

switch (result) 
{ 
case 0x41 : // Update of a gsm file 

bufptr=CatGetData (3) ; 
// write these data in the Efpuct 
CatSelect (FID_DF_GSM) ; 
CatSelect (FID_EF_PUCT) ; 
CatUpdateBinary (0,3,bufptr) ; 
break; 
case 0x36 : // change the MenuTitle for the Selectltem 

bufptr=CatGetData (sizeof (menuTitle) ) ; 

memcpy (bufptr,memuTitle, sizeof (menuTitle) ) ; 



break; 
default : 
CatExit 
break; 
} 
CatExit ; 
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Annex C (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc 


CR 


Re 

V 


Cat 


Subject/Comment 


Old 


New 


2003-03 


TP-19 


TP-030023 


001 




D 


Editorial Corrrections 


6.0.0 


6.1.0 


2007-06 


- 


- 


- 


- 


- 


Update to Rel-7 version (IVICC) 


6.1.0 


7.0.0 
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